Stripe Connect API

Flujos de onboarding y recuperación de estado para cuentas Stripe Connect Standard.

reference • updated 2026-03-15

Objetivo

Gestionar onboarding Connect Standard con contexto organizacional fuerte y callbacks deterministas.

Endpoints principales

Endpoint	Función	Resultado esperado
`POST /v1/connect/accounts/onboarding-links`	iniciar o reabrir onboarding	URL temporal de Stripe
`GET /v1/connect/accounts/return`	callback de retorno correcto	estado de cuenta actualizado en Beacon
`GET /v1/connect/accounts/refresh`	callback con requisitos pendientes	nueva sesión preservando contexto

Flujo operativo recomendado

11) Solicitar onboarding link
Llama onboarding-links con organización y modo (test|live).
22) Redirigir a Stripe
Usuario completa requisitos legales y de cobro en Connect.
33) Procesar callbacks
Gestiona return y refresh validando state firmado.
44) Actualizar dashboard
Muestra estado final y pendientes por organización.

Validaciones obligatorias en callback

state firmado válido y no expirado.
Organización del callback coincide con la sesión.
charges_enabled y details_submitted activos antes de cerrar onboarding.

Ejemplo de solicitud 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"
}

Fallos comunes y mitigación

Señal	Causa probable	Mitigación
bucle continuo de `refresh`	requisitos legales pendientes en Connect	mostrar checklist antes de reintentar
callback sin contexto	`state` inválido/expirado	reiniciar onboarding desde Beacon
cuenta conectada sin operación	capacidades incompletas	bloquear go-live hasta completar capacidades