Ir a contenido
Crea una cuenta o inicia sesión
Logotipo de la documentación de Stripe
/
Crear cuentaIniciar sesión

Crea un destinatario de Global Payout con la APIVista previa pública

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 para crear un destinatario. Debes proporcionar los siguientes parámetros para crear el ID de cuenta:

Información obligatoriaParámetro
País del destinatarioidentity.country
Tipo de negocio del destinatarioidentity.entity_type
Correo electrónico del destinatariocontact_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 activarconfiguration.recipient.capabilities

Vista previa pública

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 al crear la cuenta.

Método de transferenciaParámetro APIDescripción
Banco localconfiguration.recipient.capabilities.bank_accounts.localPermite que la cuenta reciba OutboundPayments a través de redes bancarias locales, como ACH o FPS.
Transferencia bancariaconfiguration.recipient.capabilities.bank_accounts.wirePermite que la cuenta reciba OutboundPayments a través de redes electrónicas, como Fedwire o SWIFT.
Tarjetasconfiguration.recipient.capabilities.cardsPermite 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.

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.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 en la respuesta la API Accounts. Para que el destinatario acepte las transferencias, debes proporcionar todos los requisitos que tengan la propiedad restricts_capabilities.

{
 "id": "{{CONNECTED_ACCOUNT_ID}}",
 "object": "v2.core.account",
 "applied_configurations": [
   "recipient"
 ],
 "configuration": {
   "customer": null,
   "merchant": null,
   "recipient": {

Envía la información del destinatario a Stripe

Después de recopilar la información requerida, usa la API Accounts para enviarla.

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.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 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.

Command Line
cURL
No results
curl -G https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.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 para crear el PayoutMethod real del destinatario.

El encabezado Stripe-Context en esta solicitud debe ser el ID de la cuenta del destinatario.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
" \
  --json '{
    "payout_method_data": {
        "type": "bank_account",
        "bank_account": {
            "country": "FR",
            "account_number": "FR76300060000112345678901234"
        }
    }
  }'

Nota

La respuesta OutboundSetupIntent contiene el PayoutMethod. 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 para añadir el fedwire_routing_number al PayoutMethod. Se aplican tasas adicionales. Consulta las tarifas 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 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.

El encabezado Stripe-Context en esta solicitud debe ser el ID de la cuenta del destinatario.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v2/money_management/payout_methods \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

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. Consulta Enviar dinero si quieres obtener más detalles.

En esta página