Registrar un beneficiario

El beneficiario es a quién se le paga. No hace falta darlo de alta para dispersar —puede ir en línea dentro de POST /payouts—, pero registrarlo te deja reutilizar el id y consultar su historial.

La regla que rompe integraciones: el teléfono

El riel de bolívares exige el móvil del beneficiario en los dos instrumentos, también en transferencia.

El alta no lo exige: basta con el número de cuenta. Puedes crear un beneficiario válido que después no puede cobrar y falla al dispersar con reason: "beneficiary_missing_phone".

Carga siempre el phone, aunque vayas a pagar a una cuenta.

1 · Elige el banco en el catálogo correcto

method es obligatorio en GET /payouts/banks: las dos listas no coinciden.

curl -s "$BASE/v1/payouts/banks?method=pago_movil"    -H "x-api-key: $KEY"
curl -s "$BASE/v1/payouts/banks?method=transferencia" -H "x-api-key: $KEY"

200 OK (recortado)

{
  "method": "pago_movil",
  "data": [
    { "code": "0102", "name": "Banco de Venezuela S.A.C.A. Banco Universal", "shortName": "Banco de Venezuela" },
    { "code": "0134", "name": "Banesco Banco Universal S.A.C.A.",            "shortName": "Banesco" },
    { "code": "0175", "name": "Banco Bicentenario del Pueblo de la Clase Obrera, Mujer y Comunas B.U.", "shortName": "Banco Bicentenario" }
  ]
}

	Bancos alcanzables
pago_movil	31
transferencia	24

El 0190 (Citibank) y el 0601 (Instituto Municipal de Crédito Popular) aceptan pago móvil y no transferencia. Si registras al beneficiario con un banco que ese canal no cubre, el fallo aparece al pagar, no al registrarlo.

• Un mismo código puede traer nombre distinto en cada lista: el 0175 es «Banco Bicentenario» en pago móvil y «BDT» en transferencia. Usa el nombre de la lista del instrumento con el que vas a pagar.
• La respuesta se sirve de caché y, si el catálogo no contesta, devolvemos una copia local: este endpoint no falla.
• Para el selector de bancos de tu aplicación: shortName para la interfaz, name para los comprobantes.
• Omitir method —o mandar cualquier otro parámetro de consulta— devuelve 400 validation_failed.

2 · Reúne los datos del instrumento

	pago_movil	transferencia
fullName	✅	✅
nationalId	✅	✅
bankCode	✅	✅
phone	✅	✅ también
accountNumber	—	✅

3 · Da de alta al beneficiario

1. Pago móvil

   curl -s $BASE/v1/beneficiaries \
     -H "x-api-key: $KEY" -H 'content-type: application/json' \
     -d '{"fullName":"José Marcano","nationalId":"V18234112",
          "bankCode":"0138","phone":"04141234567"}'

2. Transferencia (con el teléfono, siempre)

   curl -s $BASE/v1/beneficiaries \
     -H "x-api-key: $KEY" -H 'content-type: application/json' \
     -d '{"fullName":"María Gómez","nationalId":"V12345678",
          "bankCode":"0134","accountNumber":"01340000123456789012",
          "phone":"04141234567"}'

   201 Created

   {
     "id": "8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
     "full_name": "María Gómez", "national_id": "V12345678",
     "bank_code": "0134", "account_number": "01340000123456789012",
     "phone": "04141234567", "asset": "BS", "country": "VE",
     "status": "active", "payout_count": 0,
     "last_success_at": null, "last_failure_reason": null,
     "created_at": "2026-08-31T19:02:11.004Z", "created": true
   }

El alta es idempotente por (cédula, banco, instrumento): created: false significa que ya existía con esos datos y te devolvemos el mismo id.

Reglas de validación

Se comprueban antes de gastar una llamada al riel. Todas devuelven 400 validation_failed, y error.meta.field dice cuál falló.

Campo	Regla	Ejemplo válido
fullName	Mínimo 3 caracteres. Tal como lo tiene el banco destino	María Gómez
nationalId	V, E, J, G o P + 6 a 9 dígitos. Se normaliza a mayúsculas y sin puntos ni guiones	V12345678
bankCode	Exactamente 4 dígitos	0134
accountNumber	Sólo dígitos, 16 a 20 — en la práctica venezolana son 20 — y debe empezar por el bankCode	01340000123456789012
phone	Exactamente 04 + 9 dígitos	04141234567
—	Hace falta al menos uno de accountNumber o phone

Si la cuenta no empieza por el código de banco: El número de cuenta pertenece al banco 0102, no al 0134.

El rechazo bancario más frecuente es de titularidad

Que el nombre o la cédula no coincidan con el titular de esa cuenta o ese teléfono. Manda el fullName tal como lo tiene el banco destino, no como lo tienes tú. Se ve luego como reason: "beneficiary_mismatch" en la dispersión.

Consultar y listar

curl -s $BASE/v1/beneficiaries/8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2 -H "x-api-key: $KEY"
curl -s "$BASE/v1/beneficiaries?limit=50" -H "x-api-key: $KEY"

El listado va paginado por cursor. payout_count, last_success_at y last_failure_reason son el historial del beneficiario.

error.code	HTTP	Cuándo
beneficiary_not_found	404	No existe, o es de otro programa
beneficiary_blocked	422	Está bloqueado. No se lee ni se le dispersa

Beneficiario en línea

POST /payouts acepta el bloque beneficiary con los mismos campos, para no gastar dos llamadas por persona:

curl -s $BASE/v1/payouts -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -H 'Idempotency-Key: nomina-2026-08-0147' \
  -d '{"quoteId":"'$QUOTE'","method":"transferencia",
       "beneficiary":{"fullName":"María Gómez","nationalId":"V12345678",
                      "bankCode":"0134","accountNumber":"01340000123456789012",
                      "phone":"04141234567"}}'

Se aplica el mismo alta idempotente, así que no duplicas filas: la respuesta trae el beneficiaryId que se usó o se creó.

Siguiente paso

Dispersar bolívares.