Integra tu cuenta conectada

En calidad de plataforma, debes decidir si quieres recopilar la información solicitada de las cuentas conectadas de inmediato o de manera gradual. El onboarding inmediato recopila los requisitos eventually_due de la cuenta, mientras que el onboarding gradual solo recopila los requisitos currently_due.

Para determinar si debes utilizar el onboarding inmediato o gradual, revisa los requisitos para las ubicaciones y funcionalidades de tus cuentas conectadas. Si bien Stripe trata de minimizar el impacto en las cuentas conectadas, recuerda que los requisitos pueden cambiar con el tiempo.

Para las cuentas conectadas en las que eres responsable de la recopilación de requisitos, puedes personalizar el comportamiento de los requisitos futuros con el parámetro collection_options. Para recopilar los requisitos futuros de la cuenta, establece collection_options.future_requirements en include.

Crea un Enlace de cuenta con el ID de cuenta conectada e incluye un caso de uso.onboarding de la cuenta.url de actualización (use_case.account_onboarding.refresh_url) y un caso de uso.onboarding de la cuenta.url de retorno (use_case.account_onboarding.return_url).

Stripe redirige la cuenta conectada a la URL de actualización si la URL del enlace de cuenta ya se visitó, venció o no es válida. Stripe la redirige a la URL de retorno cuando completaron o salieron del flujo de onboarding.

Además, dependiendo de si deseas recopilar toda la información por adelantado o de forma gradual, pasa vencimiento futuro (eventually_due) o actualmente vencido (currently_due) en caso de uso.onboarding de la cuenta.opciones de recopilación (use_case.account_onboarding.collection_options.fields). En este ejemplo se pasa vencimiento futuro (eventually_due) para utilizar la incorporación por adelantado tanto para los requisitos actualmente vencido (currently_due) como para vencimiento futuro (eventually_due). Para el onboarding gradual, pasa actualmente vencido (currently_due) para recopilar solo los requisitos actualmente vencidos (currently_due) por adelantado.

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"
        }
    }
  }'

Envía tu cuenta conectada al flujo de onboarding

Proporcione la URL del enlace de cuenta para enviar a tu cuenta conectada al flujo de onboarding. Cada URL de enlace de cuenta solo se puede usar una vez, ya que otorga acceso a los datos personales del titular de la cuenta.

Configura tu integración paraescuchar los cambios de los requisitos de las cuentas. Puede probar cómo gestionar los nuevos requisitos (y cómo podrían desactivar los pagos y las transferencias) con las tarjetas de activación de prueba.

Envía una cuenta conectada de nuevo a onboarding cuando tenga algún requisito actualmente vencido (currently_due) o vence más adelante (eventually_due). No es necesario identificar los requisitos específicos, ya que la interfaz de onboarding sabe qué información necesita recopilar. Por ejemplo, si un error tipográfico impide la verificación de la identidad del titular de la cuenta, onboarding le pide que cargue un documento de identidad.

Stripe te notifica sobre cualquierpróxima actualización de los requisitos que afectan a tus cuentas conectadas. Puedes recopilar esta información de manera proactiva si revisas los requisitos de tus cuentas que tienen un código de motivos de solicitud (requested_reasons.code) de requisitos futuros (future_requirements).

En el caso de las cuentas conectadas en las que Stripe es responsable de recopilar los requisitos, dejas de recibir actualizaciones de la información de identidad después de crear un enlace de cuenta o una sesión de cuenta.

Las cuentas almacenan información de identidad en el hash identidad (identity).

Controla los errores de verificación

Escucha el evento v2.core.account[requirements].updated. Si la cuenta contiene algún requisito con un minimum_deadline.status de currently_due cuando llega la fecha límite, la funcionalidad correspondiente se desactiva y esos estados se convierten en past_due.

Dirige tus cuentas al formulario de onboarding alojado por Stripe para que rectifiquen los requisitos de verificación.

El onboarding de Connect te exige especificar una return_url y una refresh_url para gestionar todos los casos en que el usuario es remitido a tu plataforma. Es importante implementarlas correctamente para brindarle la mejor experiencia al usuario.

URL de retorno

Stripe redirige la cuenta conectada a la return_url cuando completa el flujo de onboarding o hace clic en Guardar para después en cualquier momento del flujo. Esto no significa que se recopiló toda la información o que no hay requisitos pendientes en la cuenta. Solo significa que la entrada y salida del flujo se realizó correctamente.

Esta URL no especifica ningún estado. Después de redirigir una cuenta conectada a la url de retorno (return_url), determina si la cuenta completó el onboarding de la siguiente manera:

• Recuperación de la cuenta y comprobación del hash de requisitos en busca de requisitos pendientes.
• Escucha el evento requisitos de la cuenta principal actualizados con v2 (v2.core.account[requirements].updated) para almacenar el estado de la cuenta en tu aplicación y mantenerlo actualizado.

Si el onboarding está incompleto, proporciona indicaciones en tu aplicación para permitir que la cuenta continúe con el onboarding más adelante.

Actualizar URL

Stripe redirige al usuario de la cuenta a la url de actualización (refresh_url) en los siguientes casos:

• El enlace venció (transcurrieron algunos minutos desde la creación del enlace).
• El usuario ya visitó la URL (el usuario actualizó la página o se desplazó de página en el navegador).
• Tu plataforma ya no puede acceder a la cuenta.
• El enlace se compartió en una aplicación de terceros, como un cliente de mensajería que intenta acceder a la URL para obtener una vista previa. Muchos clientes visitan automáticamente enlaces, lo que hace que un enlace de Account se venza.
• La cuenta ha sido rechazada.

Configure la url de actualización (refresh_url) para llamar a un método en tu servidor con el fin de crear un nuevo enlace de cuenta con los mismos parámetros y, a continuación, redirige la cuenta conectada a la nueva URL del enlace de cuenta.

Un usuario de cuenta que es redirigido a tu return_url podría no haber completado el proceso de onboarding. Utiliza el punto de conexión /v2/core/accounts para recuperar la Account y comprueba si configuration.recipient.capabilities.stripe_balance.stripe_transfers.status está active. Si el estado no es active y configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code tiene requirements_past_due, proporciona indicaciones en la interfaz de usuario (IU) para permitir que el usuario de la cuenta continúe con el proceso de onboarding a través de un nuevo enlace de cuenta. Gestiona otros códigos según sea necesario.

El onboarding alojado por Stripe también admite actualizaciones iniciadas por la cuenta conectada a la información que ya han proporcionado. Escucha el evento requisitos de la cuenta principal actualizados con v2 (v2.core.account[requirements].updated) enviado a tu punto de conexión de webhook para recibir una notificación cuando la cuenta complete los requisitos.

Cuando crees un enlace de cuenta, establece type en account_onboarding. Los enlaces de cuenta de este tipo proporcionan un formulario para ingresar cualquier requisito pendiente. Úsalo cuando realices el onboarding de una nueva cuenta conectada o cuando una cuenta existente tenga nuevos requisitos (como cuando solicitas una nueva funcionalidad que necesita información adicional).