Funções da conta

As funções representam funcionalidades que você pode solicitar para suas contas conectadas, como aceitar pagamentos com cartão ou receber fundos transferidos da conta da sua plataforma.

A maioria das funções exige a verificação de determinados dados da empresa da conta conectada antes que a Stripe os habilite para essa conta. As funções que você solicita para uma conta conectada determinam os dados que devem ser coletados para essa conta. Para reduzir o esforço de onboarding, solicite apenas as funções necessárias para suas contas. Solicitar mais funções significa que o fluxo de onboarding precisa verificar mais informações.

Você pode começar preenchendo o perfil da plataforma para compreender quais funções podem ser adequadas para ela.

Após criar uma conta, você pode solicitar funções adicionais e remover funções não permanentes existentes. Para contas conectadas que outras plataformas controlam, não é possível cancelar a solicitação de funções.

Funções aceitas

Veja a seguir uma lista das funções disponíveis. Clique em um item para expandi-lo ou recolhê-lo.

Várias funções

A solicitação de várias funções para uma conta conectada é comum, mas envolve as seguintes considerações:

• As funções operam de forma independente entre si.
• Se uma conta conectada tiver card_payments e transfers, e o status de qualquer um deles for inactive, ambos os recursos serão desativados.
• Você pode solicitar ou cancelar a solicitação da maioria das funções de uma conta conectada a qualquer momento durante o ciclo de vida da conta.

As funções também permitem que você colete dados para várias finalidades ao mesmo tempo. Por exemplo, você pode coletar os dados fiscais obrigatórios e os dados necessários para uma função solicitada.

Solicitar funções para uma Account

As funções são definidas no objeto Account. Para obter a lista de funções disponíveis para uma conta, use o endpoint list_capabilities.

As funções de criação e solicitação de contas diferem para contas conectadas com configurações diferentes.

• Para contas conectadas com acesso ao Stripe Dashboard completo, incluindo contas Standard , algumas funções são solicitadas automaticamente de acordo com o país. Você também pode solicitar outras funções para eles.
• Para contas conectadas com acesso ao Dashboard Express, incluindo contas Express, você pode solicitar as funções ou usar as definições de configuração de onboarding para automatizar as solicitações de função.
• Para contas conectadas sem acesso a um Dashboard hospedado pela Stripe, incluindo contas Custom, você deve solicitar as respectivas funções.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[stripe_dashboard][type]"=none \
  -d "controller[requirement_collection]"=application \
  -d country=US \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true

Os requisitos de dados variam conforme a função, mas costumam estar relacionados à verificação de identidade ou outros dados específicos de um tipo de pagamento.

Quando sua conta conectada for criada corretamente, você poderá obter uma lista de seus requisitos:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Na resposta, o hash requirements especifica as informações exigidas. Os valores de payouts_enabled e charges_enabled indicam se os repasses e as cobranças estão habilitados para a conta.

Funções para contas conectadas existentes

As seções a seguir descrevem como visualizar requisitos de dados ou gerenciar funções para contas conectadas existentes usando a API Capabilities.

Ver requisitos de dados

Você pode visualizar quais dados da sua conta conectada são necessários para uma função específica antes ou depois da solicitação dessa função.

Quando você solicita funções, account.updated webhooks é acionado e os requisitos da conta podem ser alterados. Para habilitar um requisito mais rapidamente e evitar que a conta seja desativada, visualize os requisitos e colete todos os dados necessários antes de solicitar a função.

O exemplo a seguir lista os requisitos da função card_payments para uma conta específica.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/capabilities/card_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Na resposta, verifique o hash requirements para ver quais dados são necessários:

{
  "id": "card_payments",
  "object": "capability",
  "account": 
"{{CONNECTED_ACCOUNT_ID}}",
  "requested": false,
  "requested_at": null,
  "requirements": {
    "past_due": [],
    "currently_due": ["company.tax_id", ...],
    "eventually_due": [...],
    "disabled_reason": ...,
    "current_deadline": ...,
  },
  "status": "unrequested"
}

O valor do status identifica se a função foi solicitada. Quando o valor é solicitado, os requisitos da conta estão ativos.

Além de visualizar os requisitos de uma função antes de solicitá-la, você pode usar o mesmo endpoint para visualizar os requisitos atuais de uma função. Isso pode ajudar você a se manter informado quando os requisitos mudarem.

Funções de solicitação e cancelamento de solicitação

Para solicitar uma função para uma conta, defina o valor requested da função como true atualizando a conta. Se a solicitação for bem-sucedida, a API retorna requested: true na resposta.

Para cancelar a solicitação de uma conta, defina o valor requested da função como false atualizando a conta. Se não for possível remover a função, a chamada retorna um erro. Se a chamada for bem-sucedida, a API retornará requested: false na resposta.

Você também pode solicitar e remover as funções de uma conta no Dashboard. Se uma função não puder ser removida, seu botão Remover é desativado.

O exemplo abaixo solicita a função transfers para uma conta conectada específica:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/capabilities/transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d requested=true

O exemplo abaixo solicita várias funções para uma conta conectada específica:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "capabilities[bancontact_payments][requested]"=true \
  -d "capabilities[eps_payments][requested]"=true \
  -d "capabilities[ideal_payments][requested]"=true \
  -d "capabilities[p24_payments][requested]"=true \
  -d "capabilities[sepa_debit_payments][requested]"=true

Funções descontinuadas

As funções descritas nas seções a seguir foram descontinuadas. Se for possível, não solicite-as para novas contas. Se você tiver contas existentes que usam funções descontinuadas, recomendamos atualizá-las para usar outras funções.

legacy_payments

A função legacy_payments habilita cobranças, repasses e transferências. Contas mais recentes permitem essas ações usando as funções card_payments e transfers, que aceitam configurações mais flexíveis.

Recomendamos que você siga estas etapas:

1. Atualize seu processo de onboarding de conta conectada para solicitar a combinação correta de card_payments e transfers em vez de legacy_payments.

2. Atualize suas contas conectadas existentes para solicitar a combinação correta de card_payments e transfers.

3. Atualize qualquer código que verifique o status de legacy_payments para verificar o status de um legacy_payments ou a nova função apropriada. Por exemplo, atualize o código que depende da capacidade de uma conta de fazer pagamentos com cartão para serem executados quando legacy_payments ou card_payments estiverem ativos. Da mesma forma, atualize o código que depende da capacidade de uma conta de aceitar transferências para ser executado quando legacy_payments ou transfers estiverem ativos. O código atualizado funciona durante todo o processo de transição para os novos recursos, independentemente de quando os novos recursos se tornam ativos.

4. Depois que as novas funções estiverem ativas em todas as suas contas conectadas, remova as referências a legacy_payments do seu código.

Se você faz negócios no Canadá, a Stripe solicita automaticamente card_payments e transfers para suas contas que usam legacy_payments a fim de cumprir os requisitos atualizados. Durante o processo, você pode ver os seguintes valores nas respostas da API das suas contas conectadas.

capabilities: {
  legacy_payments: "active"
},
charges_enabled: true,
payouts_enabled: true

capabilities: {
  card_payments: "inactive",
  legacy_payments: "active",
  transfers: "inactive"
},
charges_enabled: true,
payouts_enabled: true

capabilities: {
  card_payments: "active",
  legacy_payments: "active",
  transfers: "active"
},
charges_enabled: true,
payouts_enabled: true