# Onboarding hospedado pela Stripe para contas Custom

Deixe que a Stripe colete dados de verificação de identidade de contas conectadas Custom.

> #### Novas integrações do Connect
> 
> As informações nesta página se aplicam apenas a plataformas que já utilizam tipos de contas conectadas antigas. Para obter informações sobre como integrar contas conectadas com a integração hospedada pela Stripe, consulte [Integração hospedada pela Stripe](https://docs.stripe.com/connect/hosted-onboarding.md).

O [Connect Onboarding para contas Custom](https://stripe.com/connect/onboarding) é um formulário da web hospedado pela Stripe que se encarrega de coletar informações de verificação de identidade dos usuários. Ele ajusta dinamicamente os dados coletados de acordo com os recursos, o país e o tipo de empresa da conta conectada. O *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) Onboarding é a solução recomendada para coletar dados de verificação de identidade contas Custom e assegura a otimização do fluxo para:

- Navegadores de dispositivos móveis
- Acessibilidade
- Internacionalização e localização
- Taxa de conversão
- Solicitação inteligente de requisitos a partir dos dados já informados para a conta

Veja como é o formulário para a integração de amostra da Stripe,[Furever](https://furever.dev/):
![Captura de tela do formulário do Connect Onboarding](https://b.stripecdn.com/docs-statics-srv/assets/hosted_onboarding_form.e59ba8300f563e43489953f06127f52c.png)

## Como usar o Connect Onboarding para contas Custom

1. Acesse as [configurações de onboarding](https://dashboard.stripe.com/settings/connect/onboarding-interface) para personalizar a aparência do formulário. É necessário informar o nome, a cor e o ícone da sua marca. Você precisa [coletar dados da conta bancária dentro do formulário](https://dashboard.stripe.com/settings/connect/payouts/external_accounts), de forma manual ou instantânea com o [Stripe Financial Connections](https://docs.stripe.com/financial-connections.md).
1. Crie uma conta e obtenha o seu ID, ou use o ID de uma conta existente (no formato `acct_XXXXXXXX`).
1. Se você tiver informações sobre o titular da conta (como nome, endereço ou outros detalhes), poderá fornecê-las de forma proativa usando os [métodos de criação ou atualização de conta](https://docs.stripe.com/api/accounts.md). Quanto mais informações forem fornecidas pela API, menos informações o Connect Onboarding solicitará ao usuário.
1. Chame [Account Links](https://docs.stripe.com/api/account_links.md) com os seguintes parâmetros (consulte a [referência da API](https://docs.stripe.com/api/account_links.md) para saber mais):
   - `account`
   - `refresh_url`
   - `return_url`
   - `type`
   - `collection_options` (opcional)
1. No fluxo de onboarding da sua plataforma, redirecione o usuário para o `url` retornado pela API [Account Links](https://docs.stripe.com/api/account_links.md).
1. Gerencie estados de conta adicionais, redirecionando seu usuário de volta ao fluxo do Connect Onboarding, se necessário. Para gerenciar atualizações iniciadas pelos usuários de informações que eles mesmo forneceram, crie uma opção para o usuário obter um novo redirecionamento para o formulário do Connect Onboarding no Dashboard da sua plataforma.

## Determinar os dados a ser coletados

O Connect Onboarding de contas Custom aceita onboarding antecipado ou *onboarding incremental* (Incremental onboarding is a type of onboarding where you gradually collect required verification information from your users. You collect a minimum amount of information at sign-up, and you collect more information as the connected account earns more revenue). O *onboarding antecipado* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up) 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](https://docs.stripe.com/connect/identity-verification.md#onboarding-flows).

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](https://docs.stripe.com/api/account_links.md). Veja um exemplo de solicitação:

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_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"
```

## Redirecionar o usuário ao URL de Account Link

A resposta à sua solicitação de [links de conta](https://docs.stripe.com/api/account_links.md) 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](https://dashboard.stripe.com/settings/connect/payouts/external_accounts), 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.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

## Gerenciar o usuário que volta à plataforma

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.

> É possível usar HTTP para `return_url` e `refresh_url` durante os testes — por exemplo, para testar com localhost —, mas o modo de produção aceita apenas HTTPS. É necessário atualizar todas as URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe redireciona para este URL quando o usuário conclui o fluxo de integração do Connect ou clica em **Salvar para depois** em qualquer ponto do fluxo. Isso *não* significa que todas as informações foram coletadas ou que não há requisitos pendentes na conta. Significa apenas que o fluxo foi iniciado e concluído corretamente.

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](https://docs.stripe.com/api/accounts.md) 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](https://docs.stripe.com/api/account_links.md), com os mesmos parâmetros, e redirecionar o usuário ao fluxo do Connect Onboarding para criar uma experiência ideal.

## Gerenciar o fim do prazo de novos requisitos

Se ainda não fez isso, configure a integração para ouvir mudanças nos requisitos da conta. Recomendamos [usar webhooks](https://docs.stripe.com/connect/handling-api-verification.md#verification-process) para isso. Você pode testar o gerenciamento de novos requisitos (e como eles podem desativar cobranças e *repasses* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit)) com os [cartões de acionamento de teste](https://docs.stripe.com/connect/testing.md#trigger-cards).

Quando [atualizações de requisitos](https://support.stripe.com/user/questions/onboarding-requirements-updates) 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](https://docs.stripe.com/api/accounts/object.md#account_object-future_requirements). Para onboarding integrado, inclua o atributo `collectionOptions` no [componente de onboarding integrado](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). Para onboarding hospedado na Stripe, especifique o parâmetro `collection_options` ao [criar links de conta](https://docs.stripe.com/api/account_links/create.md#create_account_link-collection_options).

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.

> O Connect Onboarding para contas Custom não coleta o requisito `external_account` por padrão. Para coletar `external_account`, habilite **Coletar dados de contas externas para contas em que a plataforma é responsável por coletar requisitos** em suas [configurações de onboarding de repasses](https://dashboard.stripe.com/settings/connect/payouts/external_accounts). Saiba mais sobre [como gerenciar contas bancárias e cartões de débito](https://docs.stripe.com/connect/payouts-bank-accounts.md).

## Processar atualizações solicitadas pelo usuário

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](https://docs.stripe.com/api/account_links.md). `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”.

## Navegadores aceitos

O onboarding hospedado aceita o mesmo conjunto de navegadores que o [Stripe Dashboard aceita](https://docs.stripe.com/dashboard/basics.md):

- As últimas 20 versões principais do Chrome e Firefox
- As últimas duas versões principais do Safari e Edge
- As duas últimas versões principais do Safari móvel no iOS

O onboarding hospedado não é aceito quando integrado por meio de visualizações da web. Só é aceito em navegadores autônomos.

## See also

- [Verificação de identidade](https://docs.stripe.com/connect/identity-verification.md)