Destinatario

Un Destinatario (beneficiario) es la persona o empresa que recibe los fondos. Los destinatarios se crean usando los mismos endpoints de participantes que los remitentes — el sistema distingue los roles según cómo se usa el participantId en una transacción (campo recipientId).

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}/people
Autenticación: Nivel de tenant (x-api-key)

Ejemplo: Destinatario Brasileño

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people \
  --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/people \
  --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 Participantes

Los participantes son entidades reutilizables:

• Una persona creada como destinatario puede usarse más adelante como remitente (si cumple con los requisitos de cumplimiento)
• Una persona puede actuar como remitente y destinatario a la vez en la misma transacción (autoenvío) pasando el mismo participantId tanto para senderId como para recipientId
• Un participante solo necesita crearse una vez y puede referenciarse en un número ilimitado de transacciones futuras

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.