# Integra tu cuenta conectada Integra tus cuentas conectadas a tu Marketplace. Después de que [crees y completes previamente una cuenta conectada](https://docs.stripe.com/connect/marketplace/tasks/create.md), crea un [enlace de cuenta](https://docs.stripe.com/api/v2/core/account-links.md) y envíalo al usuario de la cuenta para que pueda completar el proceso de onboarding. Un enlace de cuenta es una URL de un solo uso que una cuenta conectada utiliza para acceder al flujo de onboarding de Connect. Como alternativa, también puedes crear un flujo de onboarding personalizado a partir de[componentes integrados](https://docs.stripe.com/connect/get-started-connect-embedded-components.md) o la [API](https://docs.stripe.com/connect/api-onboarding.md). Para simplificar el cumplimiento de la normativa y el mantenimiento, utiliza enlaces de cuenta o crea tu propio flujo de onboarding con componentes integrados. En esta guía, se utilizan enlaces de cuenta. El flujo de onboarding de Connect no le solicita a tu cuenta conectada ninguna información que hayas [completado previamente](https://docs.stripe.com/connect/marketplace/tasks/create.md#prefill-account-information), pero sí le solicita a la cuenta conectada que confirme la información completada previamente antes de aceptar el [Contrato de servicios de Connect](https://docs.stripe.com/connect/service-agreement-types.md). > El onboarding alojado por Stripe solo se admite en navegadores web. No puedes usarlo en vistas web integradas dentro de aplicaciones móviles o de escritorio. ## Determina si deseas recopilar toda la información por adelantado En calidad de plataforma, debes decidir si quieres recopilar la información solicitada de las cuentas conectadas *de inmediato* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up) o de manera *gradual* (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). El onboarding inmediato recopila los requisitos `eventually_due` de la cuenta, mientras que el onboarding gradual solo recopila los requisitos `currently_due`. | Tipo de onboarding | Ventajas | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Por adelantado** | - Normalmente, solo requiere una solicitud para toda la información - Evita la posibilidad de problemas de procesamiento y transferencia debido al incumplimiento de los plazos - Expone un riesgo potencial temprano cuando las cuentas se niegan a proporcionar información | | **Incremental** | - Las cuentas pueden integrarse rápidamente porque no tienen que proporcionar tanta información | Para determinar si debes utilizar el onboarding inmediato o gradual, revisa los [requisitos](https://docs.stripe.com/connect/required-verification-information.md) 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 del cobro de requisitos, puedes personalizar el comportamiento de los [requisitos futuros](https://docs.stripe.com/connect/handle-verification-updates.md) con el parámetro `collection_options`. Para cobrar los requisitos futuros de la cuenta, configura [collection_options.future_requirements](https://docs.stripe.com/api/v2/core/account-links/create.md#create_account_links-collection_options-future_requirements) para `poder incluir`. ### Recopilar datos públicos adicionales Stripe recopila los datos públicos obligatorios para cada cuenta conectada. Puedes elegir campos adicionales para recopilar durante el onboarding según las necesidades de tu empresa. Todos los campos que elijas y que Stripe no requiera aparecerán como opcionales, y las cuentas conectadas podrán elegir si los proporcionan. 1. En la configuración de [datos públicos](https://dashboard.stripe.com/settings/connect/onboarding-options/public-details) del Dashboard, habilita la opción **Recopilar datos públicos**. 1. Selecciona los campos que se mostrarán a las cuentas conectadas durante el onboarding. 1. Haz clic en **Guardar**. #### Campos disponibles Puedes recopilar los siguientes datos públicos: | Campo | Descripción | | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | [Descripción del cargo en el extracto bancario](https://docs.stripe.com/connect/statement-descriptors.md) | El texto que aparece en la tarjeta de crédito o extracto bancario/de tarjeta de un cliente para pagos realizados a la cuenta conectada. | | Número de teléfono de soporte para clientes | Un número de teléfono al que los clientes pueden pedir soporte relacionado con la cuenta conectada. | | Dirección de soporte para clientes | Una dirección postal que los clientes pueden usar para ponerse en contacto con la cuenta conectada. | | Correo electrónico de soporte para clientes | Una dirección de correo electrónico que los clientes pueden usar para ponerse en contacto con la cuenta conectada. | > #### Los requisitos varían > > Los requisitos de Stripe varían según la cuenta conectada según su tipo de empresa, país y funcionalidades solicitadas. Habilita campos para asegurarte de que siempre aparezcan durante el onboarding, sean o no obligatorios. ## Crear un enlace de Account Crea un [enlace de cuenta](https://docs.stripe.com/api/v2/core/account-links/create.md) con el ID de cuenta conectada e incluye un [use_case.account_onboarding.refresh_url](https://docs.stripe.com/connect/marketplace/tasks/onboard.md#refresh-url)) y un [use_case.account_onboarding.return_url](https://docs.stripe.com/connect/marketplace/tasks/onboard.md#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 curl -X POST https://api.stripe.com/v2/core/account_links \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "account": "{{CONNECTEDACCOUNT_ID}}", "use_case": { "type": "account_onboarding", "account_onboarding": { "configurations": [ "recipient" ], "refresh_url": "https://example.com/reauth", "return_url": "https://example.com/return" } } }' ``` | Parámetro | Valor | Descripción | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [account](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-account) | El ID de la cuenta conectada | Establece esto en el ID de la cuenta conectada para la que estás creando un enlace de Account. | | [use_case.type](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-type) | `account_onboarding` | Proporciona un formulario para recopilar cualquier información requerida. | | [use_case.account_onboarding.configurations](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-configurations) | `recipient` | Establece las configuraciones de la cuenta conectada. En este caso, la configuración destinatario (`recipient`) significa que puedes transferir fondos a la cuenta conectada. | | [use_case.account_onboarding.return_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-return_url) | Una URL válida | La URL a la que se redirige al usuario después de que abandone o complete el flujo de onboarding. | | [use_case.account_onboarding.refresh_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-refresh_url) | Una URL válida | La URL a la que redirigir al usuario si el enlace de Account venció, se visitó con anterioridad o no es válida. Usa esta URL para generar un nuevo enlace de Account con los mismos parámetros que usaste para crear el enlace de Account original. | ### 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. > No envíes por correo electrónico, ni por mensaje de texto ni por ningún otro medio las URL del enlace de la cuenta fuera de la aplicación de la plataforma. En lugar de eso, envíalas al titular de la cuenta autenticado dentro de tu aplicación. ## Identifica y aborda las actualizaciones de requisitos [Lado del servidor] Configura tu integración para[escuchar los cambios](https://docs.stripe.com/connect/handling-api-verification.md#verification-process) 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](https://docs.stripe.com/connect/testing.md#trigger-cards). 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 cualquier[próxima actualización de los requisitos](https://support.stripe.com/user/questions/onboarding-requirements-updates) 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](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-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](https://docs.stripe.com/api/v2/core/account-links.md) o una [sesión de cuenta](https://docs.stripe.com/api/account_sessions.md). Las cuentas almacenan información de identidad en el hash identidad (`identity`). > #### Migra un Marketplace de Accounts v1 a Accounts v2 > > Para cuentas nuevas, crea un destino de evento para [listen for v2.core.account[requirements].updated events](https://docs.stripe.com/connect/marketplace/tasks/onboard.md#handle-account-updates). Tus cuentas conectadas existentes activan eventos v1 y v2, por lo que tu integración puede administrarlos si escuchas los eventos v2 `v1.account.updated` en lugar de eventos v1 `account.updated`. ### Controla los errores de verificación Escucha el evento [v2.core.account[requirements].updated](https://docs.stripe.com/api/v2/core/events/event-types.md?api-version=preview). Si la cuenta contiene algún requisito con un estado de fecha límite mínima ([minimum_deadline.status](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-minimum_deadline-status)) que actualmente esté vencido (`currently_due`) cuando llega la fecha límite, la funcionalidad correspondiente se desactiva y esos estados se pasan a estar vencidos (`past_due`). Dirige tus cuentas al formulario de onboarding alojado por Stripe para que rectifiquen los requisitos de verificación. (See full diagram at https://docs.stripe.com/connect/marketplace/tasks/onboard) ## Gestionar el retorno del usuario a tu plataforma 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. > Debe usar HTTPS para tu url de retorno (`return_url`) y url de actualización (`refresh_url`), tanto en producción como en entornos de prueba (por ejemplo, para probar con localhost). El proceso de creación de enlace de cuenta falla si usas HTTP. ### URL de retorno Stripe redirige la cuenta conectada a la [return_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-return_url) cuando el usuario 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](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) y comprobación del hash de [requisitos](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements) 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 [refresh_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-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. ## Gestiona los usuarios que no completaron el proceso de onboarding. Un usuario de cuenta que es redirigido a tu url de retorno (`return_url`) podría no haber completado el proceso de onboardingr. Utiliza el punto de conexión /cuentas/principales/v2 (`/v2/core/accounts`) para recuperar la cuenta (`Account`) y comprueba si configuración.destinatario.capacidades.saldo de stripe.transferencias de stripe.estado ([configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status)) está activo (`active`). Si el estado no está activo (`active`) y configuración.destinatario.capacidades.saldo de stripe.transferencias de stripe.detalles del estado.código ([configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code)) tiene requisitos vencidos (`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. ## Gestiona las actualizaciones de la cuenta conectada [Lado del servidor] 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). ## Próximos pasos Cuando tu cuenta conectada esté activa, [habilita los métodos de pago](https://docs.stripe.com/connect/marketplace/tasks/enable-payment-methods.md) que quieras aceptar.