Onboarding hospedado pela Stripe para contas Custom

O Connect Onboarding de contas Custom aceita onboarding antecipado ou onboarding incremental. O onboarding antecipado coleta os requisitos de eventually_due da conta, e o onboarding incremental coleta os requisitos de currently_due. Para conhecer as vantagens e desvantagens das duas opções, consulte a documentação dos fluxos de onboarding.

Os requisitos currently_due solicitam apenas os dados do usuário necessários naquele momento. Os requisitos eventually_due formam um questionário mais completo, que será necessário em algum momento.

De acordo com as necessidades da plataforma, passe currently_due ou eventually_due como valor do parâmetro collection_options.fields nas chamadas para Account Links. Veja um exemplo de solicitação:

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]"=eventually_due

A resposta à sua solicitação de links de conta inclui um valor para a chave url. Redirecione seu usuário a este link para enviá-lo ao fluxo. Você só pode usar os URLs de links de conta uma vez porque eles concedem acesso aos dados pessoais do titular da conta. Autentique o usuário no aplicativo antes de redirecioná-lo para esse URL. Se você habilitar Coletar dados de contas externas para contas em que a plataforma é responsável por coletar requisitos em suas configurações de onboarding de repasses, ou se a função treasury for solicitada, o usuário deverá configurar uma autenticação adicional com a Stripe antes de entrar no fluxo de onboarding.

O Connect Onboarding exige a passagem de return_url e refresh_url para processar todos os casos de redirecionamento de usuário à plataforma. É importante que esse processamento seja implementado corretamente para oferecer a melhor experiência aos usuários.

return_url

A Stripe emite um redirecionamento de volta a este URL quando o usuário conclui o fluxo do Connect Onboarding ou clica em “Salvar para mais tarde” em qualquer ponto do fluxo. Isso não significa que todos os dados foram coletados ou que não há requisitos pendentes na conta. É simplesmente uma indicação de que o fluxo foi iniciado e encerrado adequadamente.

Nenhum estado é passado com esse URL. Depois que um usuário é redirecionado para o seu return_url, verifique o estado do atributo requirements na conta dele. Você pode escutar webhooks account.updated ou acessar o objeto Account e inspecionar o estado do atributo requirements. Veja mais detalhes na Etapa 4 abaixo.

refresh_url

O usuário será redirecionado para refresh_url nestes casos:

• O link expirou (alguns minutos se passaram desde a criação do link)
• O link já foi acessado (o usuário atualizou a página ou clicou no botão Voltar/Avançar)
• O link foi compartilhado em um aplicativo de terceiros, como um cliente de mensagens que tenta acessar o URL para visualizá-lo. Muitos clientes acessam automaticamente links que fazem com que eles expirem

O refresh_url deve acionar um método no servidor para chamar novamente a API Account Links, com os mesmos parâmetros, e redirecionar o usuário ao fluxo do Connect Onboarding para criar uma experiência ideal.

Se ainda não fez isso, configure a integração para ouvir mudanças nos requisitos da conta. Recomendamos usar webhooks para isso. Você pode testar o gerenciamento de novos requisitos (e como eles podem desativar cobranças e repasses) com os cartões de acionamento de teste.

Quando atualizações de requisitos afetarem suas contas conectadas, notificaremos você.

Se você usa onboarding integrado ou hospedado pela Stripe, pode coletar dados de forma proativa para cumprir requisitos futuros. Para onboarding integrado, inclua o atributo collectionOptions no componente de onboarding integrado. Para onboarding hospedado na Stripe, especifique o parâmetro collection_options ao criar links de conta.

De acordo com as necessidades de verificação do aplicativo, encaminhe o usuário de volta ao Connect Onboarding, se necessário, para cumprir os requisitos currently_due ou eventually_due descritos na etapa 1. Isso pode ser usado como indicador de quando devolver o usuário ao fluxo. Lembre-se de que, com o Connect Onboarding, você não precisa se preocupar com quais são os requisitos. Basta encaminhar o usuário e o Connect Onboarding coleta os dados corretos.

Por exemplo, quando o usuário erra a digitação dos dados e não consegue ser verificado, ele talvez tenha que fornecer um documento de identificação (por exemplo, uma carteira de habilitação nos Estados Unidos). Enviado de volta ao Connect Onboarding, o usuário pode carregar esse documento para garantir sua verificação.

A maior parte do uso do Connect Onboarding discutido até agora tem sido sobre solicitar que o usuário forneça novas informações. O Connect Onboarding também aceita atualizações das informações fornecidas pelo usuário no parâmetro type do link da conta. type aceita um de dois valores: account_onboarding ou account_update.

account_onboarding

Esse valor de type proporciona um meio de informar requisitos pendentes. Use-o no onboarding de novos usuários ou quando surgirem novos requisitos para usuários existentes. Envie o usuário ao formulário neste modo para coletar apenas os novos dados necessários.

account_update

Esse valor de type exibe os atributos já preenchidos no objeto Account e permite que o usuário edite dados previamente informados. Forneça um ponto de acesso no site da plataforma a um Account Link type=account_update para que os usuários façam atualizações (por exemplo, quando mudam de endereço). Considere enquadrar o link como “Editar meu perfil” ou “Atualizar meus dados de verificação”.