Cuenta del Destinatario

Una Cuenta del Destinatario representa la cuenta bancaria o el destino del payout donde se entregarán los fondos. Antes de crear una cuenta de destinatario, primero debe crear el destinatario como participante y obtener el esquema de cuenta del país de destino.

Creación Basada en Esquemas

Los requisitos de la cuenta del destinatario varían por país. Obtenga siempre el esquema de la cuenta antes de construir su formulario o su llamada a la API:

# Obtener el esquema de cuenta para Colombia
curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/recipientAccounts/schema/co \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

El esquema devuelve un objeto JSON Schema (draft-07) que define los campos requeridos, los valores permitidos y las reglas de validación. Los campos comunes incluyen:

Consejo: Para los países que requieren un bankCode, use el endpoint de Bancos en un País para poblar un menú desplegable en su interfaz.

Creación de una Cuenta de Destinatario

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/recipientAccounts/gateway
Autenticación: A nivel de agente (x-api-key + x-agent-id + x-agent-api-key)

Cuerpo de la Solicitud

Campos por tipo de método de payout:

El esquema de cuenta de cada país es la fuente de verdad sobre qué tipos y campos admite su corredor.

Ejemplo: Colombia (Depósito Bancario)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-co-001",
  "asset": "COP",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "CO",
    "bankCode": "1001",
    "routingNumber": "1234",
    "accountNumber": "9876543210",
    "accountType": "SAVINGS"
  }
}'

Ejemplo: México (CLABE)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-mx-001",
  "asset": "MXN",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "MX",
    "bankCode": "002",
    "routingNumber": "002",
    "accountNumber": "012345678901234567",
    "accountType": "CHECKING"
  }
}'

Ejemplo: Perú (Depósito Bancario)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-pe-001",
  "asset": "PEN",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "PE",
    "bankCode": "BINPPEPL",
    "routingNumber": "1234",
    "accountNumber": "1345",
    "accountType": "CHECKING"
  }
}'

Guarde el id devuelto — este es el recipientAccountId requerido al crear una transacción.

Obtener una Cuenta de Destinatario

Endpoint: GET /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}
Autenticación: A nivel de agente

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

Los campos sensibles (accountNumber, routingNumber, la key de PIX) se devuelven enmascarados — los valores completos nunca se exponen después de la creación.

Eliminar una Cuenta de Destinatario

Endpoint: DELETE /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}
Autenticación: A nivel de agente

curl --request DELETE \
  --url https://{FQDN}/organizations/$TENANT/payout/recipientAccounts/$ACCOUNT_ID \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Devuelve 204 No Content.

Requisitos Específicos por País

Use siempre el endpoint de esquema como fuente de verdad — la tabla anterior es solo orientativa.

Flujo de Trabajo de Integración

1. Fetch account schema  →  GET /payout/recipientAccounts/schema/{countryCode}
2. Fetch bank list        →  GET /payout/{countryCode}/banks (if bankCode is required)
3. Collect user input     →  Build form from schema
4. Create account         →  POST /payout/participants/{id}/recipientAccounts/gateway
5. Save account ID        →  Use in POST /fx/transactions

Todos los Endpoints

Documentación Interactiva de la API