Destinatario

Un Destinatario (beneficiario) es la persona o empresa que recibe los fondos. Los destinatarios se crean en su propio endpoint por rol, POST /v2/beneficiaries, que registra a la persona con el rol BENEFICIARY. Los remitentes tienen un endpoint paralelo, POST /v2/senders.

⚠️ Los endpoints /people están obsoletos. Integraciones anteriores creaban remitentes y destinatarios mediante el endpoint compartido POST /people y dejaban que el rol se infiriera de cómo se usaba el ID en una transacción. Ese modelo queda superado — crea destinatarios en POST /v2/beneficiaries y remitentes en POST /v2/senders. Las rutas heredadas /people y /v2/people siguen activas para la migración (ambas estampan SENDER), por lo que no pueden crear un beneficiario — usa la ruta por rol.

Creación de Destinatarios Basada en Esquemas

Los requisitos de datos del destinatario varían según el país de destino. Antes de recopilar datos del usuario, siempre obtén el esquema del destinatario:

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/recipients/schema/co \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Esto devuelve un JSON Schema (draft-07) que define exactamente qué campos son requeridos para ese país. Ver Esquema de Destinatario para más detalles.

Crear un Destinatario

Endpoint: POST /organizations/{tenant}/v2/beneficiaries
Autenticación: Nivel de tenant (x-api-key)

La estructura de la solicitud coincide con la del endpoint de remitente — los beneficiarios también son filas de persons, distinguidas solo por el rol — y ejecuta el mismo pipeline de validación de documentos. Una creación devuelve 201 (o 200 si ya existe una persona con el mismo externalId).

Ejemplo: Destinatario Brasileño

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/beneficiaries \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "Maria",
  "lastName": "Silva",
  "phoneNumber": "+5511999998888",
  "documents": [
    {
      "type": "cpf",
      "document": "12345678901",
      "countryCode": "BR"
    }
  ]
}'

Ejemplo: Destinatario Colombiano

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/beneficiaries \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "Carlos",
  "lastName": "Gutierrez",
  "phoneNumber": "+573001234567",
  "address": {
    "countryCode": "CO",
    "city": "Bogotá",
    "line1": "Calle 100 #15-20"
  },
  "documents": [
    {
      "type": "cc",
      "document": "1234567890",
      "countryCode": "CO"
    }
  ]
}'

Guarda el id devuelto — este es el recipientId que se usa en la transacción.

Tipos de Documento Específicos por País

Siempre consulta el esquema del destinatario para obtener la lista autoritativa de tipos de documento aceptados por país.

Reutilización de Destinatarios

Un destinatario solo necesita crearse una vez y puede referenciarse como el recipientId en un número ilimitado de transacciones futuras.

Una persona se crea con un único rol. Si el mismo individuo necesita enviar y recibir, créalo una vez en cada endpoint (/v2/senders y /v2/beneficiaries) — el rol de remitente conlleva las obligaciones completas de KYC/cumplimiento, mientras que el rol de beneficiario se limita a recibir payouts.

Después de Crear el Destinatario

Una vez que tienes el recipientId, el siguiente paso es vincular una cuenta bancaria:

1. Obtén el esquema de la cuenta — GET /payout/recipientAccounts/schema/{countryCode}
2. Obtén la lista de bancos (si es requerida) — GET /payout/{countryCode}/banks
3. Crea la cuenta del destinatario — POST /payout/participants/{recipientId}/recipientAccounts/gateway

Ver Cuenta del Destinatario para todos los detalles.

Mejores Prácticas

• Siempre usa el endpoint de esquema para determinar los campos requeridos — no codifiques de forma fija los requisitos de campos por país.
• Renderiza formularios dinámicamente basándote en la respuesta del esquema para soportar automáticamente nuevos países.
• Recopila solo los campos requeridos — enviar datos innecesarios puede activar verificaciones de cumplimiento adicionales.
• Valida la entrada del lado del cliente usando las restricciones pattern, minLength y enum del esquema antes de enviar.
• Maneja el requisito de address — algunos países requieren la dirección del destinatario, otros no. El esquema es tu fuente de verdad.