# Crea un destinatario de Global Payout con la API Descubre cómo hacer el onboarding de nuevos destinatarios de Global Payouts con la API de Stripe. Crea un flujo de recogida de información para solicitar la información necesaria de los destinatarios y sus métodos de pago, y envía esos datos a Stripe a través de nuestras API. ## Consideraciones Tu empresa es responsable de todas las interacciones con tus destinatarios y de recoger toda la información necesaria para verificarlos. Stripe actualiza los requisitos de verificación de los destinatarios a medida que cambian las leyes y normativas en todo el mundo. Cuando diseñes tu integración para enviar pagos, ten en cuenta cómo gestionar estos aspectos: - La revisión periódica de los cambios en los requisitos legales y normativos. - La actualización de la lógica de tu aplicación en respuesta a estos cambios. Planea revisar y actualizar los requisitos de onboarding regularmente para evitar fallos en las transferencias. ## Crea un destinatario Al utilizar un formulario para recoger la información sobre el destinatario del pago, utiliza la [API Accounts v2](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview) para crear un destinatario. Debes proporcionar los siguientes parámetros para crear el ID de `cuenta`: | Información obligatoria | Parámetro | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | País del destinatario | `identity.country` | | Tipo de negocio del destinatario | `identity.entity_type` | | Correo electrónico del destinatario | `contact_email` | | El nombre de usuario de la `cuenta`. Aparece en el Dashboard de Stripe y en cualquier factura que envíes a la `cuenta`. | `display_name` | | Métodos de pago que quieres activar | `configuration.recipient.capabilities` | > Las transferencias transfronterizas para remitentes de EE. UU. están disponibles en vista previa pública. Debes especificar los tipos de métodos de transferencia previstos [solicitando las funcionalidades correspondientes](https://docs.stripe.com/connect/account-capabilities.md?accounts-namespace=v2) al [crear la cuenta](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview#v2_create_accounts-configuration-recipient-capabilities). | Método de transferencia | Parámetro API | Descripción | | ----------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Banco local | `configuration.recipient.capabilities.bank_accounts.local` | Permite que la `cuenta` reciba `OutboundPayments` a través de redes bancarias locales, como ACH o FPS. | | Transferencia bancaria | `configuration.recipient.capabilities.bank_accounts.wire` | Permite que la `cuenta` reciba `OutboundPayments` a través de redes electrónicas, como Fedwire o SWIFT. | | Tarjetas | `configuration.recipient.capabilities.cards` | Permite que la `cuenta` reciba `OutboundPayments` en redes de tarjetas de débito, como Visa Direct o Mastercard Send. | Un destinatario puede tener habilitados varios tipos de métodos de transferencia. No todos los tipos de métodos de transferencia están disponibles para los destinatarios de todos los países. Consulta la lista completa de [métodos disponibles por país](https://docs.stripe.com/global-payouts/recipient-creation-options.md#requirements-for-supported-recipient-countries). Algunas funcionalidades requieren información adicional sobre tu destinatario. Por ejemplo, `configuration.destinatario.capabilities.bank_accounts.local` para un destinatario de EE. UU. requiere que envíes un número de cuenta y de ruta. Después solicitar las funcionalidades del método de transferencia, Stripe determina los requisitos de información adicional que debes enviar para habilitarlas y puede identificarlo en la respuesta API. Para recibir los requisitos en la respuesta, incluye `requirements`, `configuration.recipient` e `identity` en la matriz `include`. De lo contrario, Stripe devuelve una respuesta nula para esas propiedades, independientemente de sus valores reales. ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "contact_email": "jenny.rosen@example.com", "display_name": "Jenny Rosen", "identity": { "country": "us", "entity_type": "individual" }, "configuration": { "recipient": { "capabilities": { "bank_accounts": { "local": { "requested": true } } } } }, "include": [ "identity", "configuration.recipient", "requirements" ] }' ``` ## Determina los campos necesarios para activar a un destinatario Para identificar los requisitos específicos que debes presentar, inspecciona la matriz [requirements.entries](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview#v2_create_accounts-response-requirements-entries) en la respuesta la API Accounts. Para que el destinatario acepte las transferencias, debes proporcionar todos los requisitos que tengan la propiedad `restricts_capabilities`. ```json { "id": "{{CONNECTED_ACCOUNT_ID}}", "object": "v2.core.account", "applied_configurations": [ "recipient" ], "configuration": { "customer": null, "merchant": null, "recipient": { "capabilities": { "bank_accounts": { "local": { "requested": true, "status": "restricted", "status_details": [ { "code": "requirements_past_due", "resolution": "provide_info" } ] }, "wire": null, "instant": null }, "cards": null, "stripe_balance": null }, "default_outbound_destination": null } }, "contact_email": "jenny.rosen@stripe.com", "created": "2025-04-02T17:20:00.000Z", "dashboard": null, "identity": { "attestations": { "directorship_declaration": null, "ownership_declaration": null, "persons_provided": { "directors": null, "executives": null, "owners": null, "ownership_exemption_reason": null }, "terms_of_service": { "account": null } }, "business_details": null, "country": "US", "entity_type": "individual", "individual": null }, "defaults": null, "display_name": "Jenny Rosen", "metadata": {}, "requirements": { "collector": "stripe", "entries": [ { "awaiting_action_from": "user", "description": "identity.individual.given_name", "errors": [], "impact": {"restricts_capabilities": [ { "capability": "bank_accounts.local", "configuration": "recipient", "deadline": { "status": "past_due" } } ], "restricts_payouts": null }, "minimum_deadline": { "status": "past_due" }, "reference": null, "requested_reasons": [ { "code": "routine_onboarding" } ] }, { "awaiting_action_from": "user", "description": "identity.individual.surname", "errors": [], "impact": { "restricts_capabilities": [ { "capability": "bank_accounts.local", "configuration": "recipient", "deadline": { "status": "past_due" } } ], "restricts_payouts": null }, "minimum_deadline": { "status": "past_due" }, "reference": null, "requested_reasons": [ { "code": "routine_onboarding" } ] } ], "summary": { "minimum_deadline": { "status": "past_due", "time": null } } } } ``` ## Envía la información del destinatario a Stripe Después de recopilar la información requerida, usa la [API Accounts](https://docs.stripe.com/api/v2/core/accounts/update.md?api-version=preview) para enviarla. ```curl curl -X POST https://api.stripe.com/v2/core/accounts/{{CONNECTEDACCOUNT_ID}} \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "contact_email": "jenny.rosen@example.com", "display_name": "Jenny Rosen", "identity": { "country": "us", "entity_type": "individual", "individual": { "given_name": "Jenny", "surname": "Rosen", "address": { "city": "Brothers", "country": "US", "line1": "27 Fredrick Ave", "postal_code": "97712", "state": "OR" } } }, "include": [ "identity" ] }' ``` ## Confirma que el destinatario está habilitado [Recupera la cuenta](https://docs.stripe.com/api/v2/core/accounts/retrieve.md?api-version=preview) e inspecciona el `status` de las funcionalidades que has solicitado. El `status` debe estar `active` para que un destinatario reciba transferencias según tu método de transferencia especificado. ```curl curl -G https://api.stripe.com/v2/core/accounts/{{CONNECTEDACCOUNT_ID}} \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ -d "include[0]=configuration.recipient" ``` ## Crea métodos de transferencia para tus destinatarios Después de habilitar la funcionalidad del método de transferencia, usa la [API Setup Intents saliente](https://docs.stripe.com/api/v2/money-management/outbound-setup-intents/create.md?api-version=preview) para crear el `PayoutMethod` real del destinatario. El encabezado Stripe-Context en esta solicitud debe ser el ID de la cuenta del destinatario. ```curl curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ -H "Stripe-Context: {{CONTEXT_ID}}" \ --json '{ "payout_method_data": { "type": "bank_account", "bank_account": { "country": "FR", "account_number": "FR76300060000112345678901234" } } }' ``` > La respuesta `OutboundSetupIntent` contiene [el PayoutMethod](https://docs.stripe.com/api/v2/money-management/outbound-setup-intents/create.md?api-version=preview#v2_create_outbound_setup_intents-response-payout_method). Al realizar un `OutboundPayment`, utiliza el ID del `PayoutMethod` (por ejemplo, `frba_test_...`) de la respuesta, no del ID de `OutboundSetupIntent` (`osi_test_...`). Para enviar transferencias electrónicas, utiliza la [API Accounts de bancos estadounidenses](https://docs.stripe.com/api/v2/core/vault/us-bank-accounts/update.md?api-version=preview) para añadir el `fedwire_routing_number` al `PayoutMethod`. Se aplican tasas adicionales. Consulta las [tarifas](https://docs.stripe.com/global-payouts/pricing.md) si deseas obtener más detalles. También puedes usar tarjetas de débito como método de transferencia. Sin embargo, tus destinatarios deben enviar la información de su tarjeta de débito directamente a Stripe. Si te interesa habilitar pagos con tarjetas de débito, utiliza la [API Account Links](https://docs.stripe.com/api/v2/core/account-links.md) Para crear un formulario compartible para que tu usuario pueda enviar sus credenciales de la tarjeta de débito. ## Consulta todos los métodos de transferencia para un destinatario Utiliza la API de métodos de transferencia para [recuperar los PayoutMethods de un destinatario](https://docs.stripe.com/api/v2/money-management/payout-methods/list.md?api-version=preview). El encabezado Stripe-Context en esta solicitud debe ser el ID de la `cuenta` del destinatario. ```curl curl https://api.stripe.com/v2/money_management/payout_methods \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ -H "Stripe-Context: {{CONTEXT_ID}}" ``` La respuesta contiene una lista de objetos `PayoutMethod` que posee el destinatario. Utiliza un ID del `PayoutMethod` para realizar una transferencia usando la [API de pagos salientes](https://docs.stripe.com/api/v2/money-management/outbound-payments/create.md?api-version=preview). Consulta [Enviar dinero](https://docs.stripe.com/global-payouts/send-money.md) si quieres obtener más detalles.