Integre sua conta conectada

Como plataforma, você precisa decidir se quer coletar os dados obrigatórios das contas conectadas de forma antecipada ou incremental. O onboarding antecipado coleta os requisitos eventually_due da conta, enquanto o onboarding incremental coleta somente os requisitos currently_due.

Para determinar se você deve usar o onboarding antecipado ou incremental, revise os requisitos para a localização e as funções das suas contas conectadas. Embora a Stripe tente minimizar o impacto nas contas conectadas, os requisitos podem mudar com o tempo.

Para contas conectadas em que você é responsável pela coleta de requisitos, é possível personalizar o comportamento dos requisitos futuros usando o parâmetro collection_options. Para coletar os requisitos futuros da conta, defina collection_options.future_requirements como include.

Crie um Link da conta usando o ID conta conectada e inclua um use_case.account_onboarding.refresh_url e umuse_case.account_onboarding.return_url.

A Stripe redireciona a conta conectada para a URL de recarregar se a URL do Link da conta já tiver sido visitada, tiver expirado ou for inválida. A Stripe redireciona para o URL de retorno quando eles concluem ou saem do fluxo de onboarding.

Além disso, dependeno se deseja recolher todas as informações antecipadamente ou recolher-las de forma incremental, transmitaeventually_due ou currently_due em use_case.account_onboarding.collection_options.fields. Este exemplo transmite eventually_due para usar onboarding inicial para ambos os requisitos currently_due e eventually_due. Para onboarding incremental, transmita currently_due para recolher apenas os requisitos currently_due antecipadamente.

curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

Envie sua conta conectada para o fluxo de onboarding

Forneça a URL do Link da conta para enviar sua conta conectada para o fluxo de onboarding. Cada URL do Link da Conta só pode ser usado uma vez, pois concede acesso aos dados pessoais do titular da conta.

Configure sua integração para ouvir as alterações de requisitos da conta. Teste o tratamento de novos requisitos (e como eles podem desabilitar encargos e pagamentos) com os cartões de gatilho de teste.

Envie uma conta conectada de volta por meio do onboarding quando houver algum requisito currently_due ou eventually_due. Não é necessário identificar os requisitos específicos, porque a interface de onboarding sabe quais as informações precisa de recolher. Por exemplo, se um erro de digitação estiver impedindo a verificação da identidade do proprietário da conta, onboarding solicitará que ele carregue um documento de identidade.

A Stripe notifica você sobre quaisquer próximas atualizações de requisitos que afetam suas contas conectadas. Você pode recolher essas informações de forma proativa revisando os requisitos de suas contas que têm umrequested_reasons.code defuture_requirements.

Para contas conectadas em que a Stripe é responsável por coletar requisitos, pare de receber atualizações de dados de identificação depois de criar um Link da conta ou uma Sessão da conta.

As contas armazenam dados de identificação no hash identity.

Lidar com erros de verificação

Ouça o evento v2.core.account[requirements].updated. Se a conta contiver requisitos com umminimum_deadline.status decurrently_due quando o prazo chega, a funcionalidade correspondente será desabilitada e esses status se tornam past_due.

Permita que suas contas corrijam os requisitos de verificação direcionando-as para o formulário de onboarding hospedado pela Stripe.

O Connect Onboarding exige que você passe um return_url e um refresh_url para gerenciar todos os casos em que o usuário é redirecionado à sua plataforma. É importante implementá-los corretamente para proporcionar a melhor experiência ao usuário.

URL de retorno

A Stripe redireciona a conta conectada de volta para return_url quando o usuário conclui o fluxo de onboarding ou clica em Salvar para depois em qualquer momento do fluxo. Isso não significa que todas as informações tenham sido coletadas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi iniciado e encerrado corretamente.

Essa URL não passa nenhum estado. Depois de redirecionar uma conta conectada para return_url, determine se a conta concluiu o onboarding por um dos seguintes meios:

• Como recuperar a conta e verificar os requisitos do hash para verificar se há requisitos pendentes.
• Armazenar em cache o status da conta em sua inscrição e mantê-lo atualizado ouvindo o evento v2.core.account[requirements].updated.

Se o onboarding estiver incompleto, forneça prompts em sua inscrição para permitir que a conta continue o onboarding mais tarde.

Atualizar URL

Stripe redireciona o usuário da conta para refresh_url nos seguintes casos:

• O link expirou (alguns minutos se passaram após a criação do link).
• O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
• Sua plataforma não consegue mais acessar a conta.
• O link foi compartilhado em um aplicativo de terceiros, como um cliente de mensagens que tenta acessar o URL para fazer preview. Muitos clientes acessam links automaticamente, o que faz com que um link da conta expire.
• A conta foi recusada.

Configure refresh_url para chamar um método em seu servidor para criar um novo Link de conta com os mesmos parâmetros e, em seguida, redirecionar a conta conectada para o novo URL do Link da conta.

Um usuário da conta que é redirecionado ao seu return_url pode não ter concluído o processo de onboarding. Use o endpoint /v2/core/accounts para recuperar a Account e verifique se configuration.recipient.capabilities.stripe_balance.stripe_transfers.status é active. Se o status não for active e configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code for requirements_past_due, forneça prompts na IU para permitir que o usuário da conta continue o processo de onboarding por meio de um novo link de conta. Trate outros códigos conforme necessário.

O onboarding hospedado pela Stripe também oferece suporte a atualizações iniciadas pela conta conectada para as informações que elas já forneceram. Ouça o evento v2.core.account[requirements].updated enviado ao seu Webhook endpoint para ser notificado quando a conta concluir os requisitos.

Ao criar um link de conta, defina type como account_onboarding. Links de conta desse tipo fornecem um formulário para inserir eventuais requisitos pendentes. Use-o ao integrar uma nova conta conectada ou quando uma conta existente tiver novos requisitos (como ao solicitar um novo recurso que precise de informações adicionais).