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 los destinatarios para los Global Payouts usando la API de Stripe.

Crea un flujo de recogida de información para que tus destinatarios recojan detalles de los destinatarios y métodos de pago, y después envía esa información 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.

Al construir una integración de pagos, considera cómo gestionar:

  • 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.

Crear 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 métodos de transferencia previstos con la API Accounts v2 porque algunos métodos necesitan información adicional sobre tu destinatario antes de que puedan habilitarse. Los métodos que habilitas usando el parámetro funcionalidades determinan la información que debes solicitar a tu destinatario. Por ejemplo, configuration.recipient.capabilities.bank_accounts.local para un destinatario en EE. UU. requiere que envíes una cuenta y número de ruta.

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 métodos de transferencia. No todos los 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.

Después de añadir estos campos y los métodos de pago solicitados, Stripe determina la información adicional requerida en la respuesta de la API que debes enviar para que el destinatario esté listo para recibir las transferencias. Para cumplir estos requisitos, incluye Requisitos, configuration.receiver e Identidad en la matriz incluir. De lo contrario, Stripe devuelve una respuesta nula, independientemente de su valor real.

Cuando creas, recuperas o actualizas una cuenta, ciertos campos solo aparecen en la respuesta si los especificas en el parámetro incluir. Para cualquiera de esos campos que no especifiques, la respuesta los incluye como nulos, independientemente de su valor real.

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: 2025-12-15.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"
    ]
  }'

Determinar los campos necesarios para activar a un destinatario

Utiliza la respuesta de la API Accounts v2 para inspeccionar el requirements.entries para determinar qué campos específicos necesitas enviar a Stripe. Cualquier entrada que tiene las restricts_capabilities Se requieren campos para que el destinatario acepte las transferencias.

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

Enviar información del destinatario a Stripe

Después de determinar los campos adicionales que necesitas enviar, usa la API Accounts v2 para presentar la información requerida. Utiliza el id de la respuesta anterior en la URI.

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: 2025-12-15.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

Usa la API Accounts v2 para recuperar una cuenta e inspeccionar el estado de las funcionalidades que has solicitado. El estado debe estar activo 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: 2025-12-15.preview" \
  -d "include[0]"="configuration.recipient"

Crea métodos de transferencia para tus destinatarios

Utiliza la API OutboundSetupIntents v2 para enviar los datos del método de transferencia a Stripe para que se pueda realizar una transferencia al 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: 2025-12-15.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 método de transferencia anidado en su interior. Al realizar un OutboundPayment, utiliza el ID del método de transferencia (por ejemplo, frba_test_...) de la respuesta, no del ID de OutSetupIntent (osi_test_...).

Para enviar pagos por transferencia bancaria, utiliza la API USBankAccount v2 para añadir el fedwire_routing_number Al método de pago. Se aplican tasas adicionales. Consulta los Precios 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 v2 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

Consulta todos los métodos de transferencia creados para un destinatario. Llama a la API Payout Methods v2 y proporcionar el ID 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 https://api.stripe.com/v2/money_management/payout_methods \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

La respuesta contiene una lista de objetos PayoutMethod que posee el destinatario. Utiliza los IDs de método de transferencia para realizar una transferencia usando la API OutboundPayments. Consulta Enviar dinero si deseas obtener más detalles.