Stripe Connect API

Fluxos de onboarding e recuperação de estado para contas Stripe Connect Standard.

reference • updated 2026-03-15

Objetivo

Gerir onboarding Connect Standard de forma auditável, preservando contexto de organização e reduzindo loops entre return e refresh.

Endpoints principais

Endpoint	Função	Resultado esperado
`POST /v1/connect/accounts/onboarding-links`	iniciar/reabrir onboarding	URL temporária para Stripe
`GET /v1/connect/accounts/return`	callback de retorno com sucesso	estado da conta atualizado no Beacon
`GET /v1/connect/accounts/refresh`	callback para requisitos pendentes	nova sessão de onboarding com contexto preservado

Fluxo operacional recomendado

11) Pedir onboarding link
Chama onboarding-links com organização, modo (test|live) e utilizador responsável.
22) Redirecionar para Stripe
Utilizador completa dados legais e capacidades de cobrança no Connect.
33) Tratar callbacks
Processa return e refresh com validação de state assinado.
44) Atualizar dashboard
Mostra estado final e pendências por organização em tempo real.

Validações obrigatórias no callback

state assinado e ainda válido temporalmente.
Correspondência entre organização em sessão e organização no callback.
Estado charges_enabled e details_submitted antes de marcar onboarding como concluído.

Exemplo de pedido de onboarding link

bash

curl -X POST https://api.beacon.pt/v1/connect/accounts/onboarding-links \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization_id>",
    "mode": "test",
    "returnUrl": "https://app.beacon.pt/dashboard/connect/return",
    "refreshUrl": "https://app.beacon.pt/dashboard/connect/refresh"
  }'

json

{
  "onboardingUrl": "https://connect.stripe.com/setup/c/acct_123/...",
  "expiresAt": "2026-03-15T11:00:00Z"
}

Falhas comuns e mitigação

Sinal	Causa provável	Mitigação
loop `refresh` contínuo	requisitos legais pendentes no Connect	mostrar checklist de pendências antes de relançar fluxo
callback sem contexto	`state` inválido/expirado	reiniciar onboarding a partir do Beacon
conta ligada mas sem operação	permissões incompletas	validar capacidades no Stripe e bloquear go-live