Register a beneficiary

The beneficiary is who gets paid. You do not need to register them to pay out —they can go inline inside POST /payouts—, but registering them lets you reuse the id and look up their history.

The phone number: required for pago móvil, optional for bank transfer

With pago_movil the beneficiary’s mobile number is the destination: without it the payout fails with reason: "beneficiary_missing_phone".

With transferencia the money goes to the account number and phone is optional. If you have it, include it anyway: a beneficiary with both a mobile number and an account can get paid by either method.

1 · Pick the bank from the right catalog

method is required in GET /payouts/banks: the two lists do not match.

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 (trimmed)

{
  "method": "pago_movil",
  "data": [
    { "code": "0102", "name": "Banco de Venezuela S.A.C.A. Banco Universal", "shortName": "Banco de Venezuela" },
    { "code": "0105", "name": "Banco Mercantil, C.A. Banco Universal",       "shortName": "Mercantil" },
    { "code": "0134", "name": "Banesco Banco Universal S.A.C.A.",            "shortName": "Banesco" }
  ]
}

	Reachable banks
pago_movil	31
transferencia	24

0190 (Citibank) and 0601 (Instituto Municipal de Crédito Popular) accept pago móvil and not bank transfer. If you register the beneficiary with a bank that channel does not cover, the failure shows up at payment time, not at registration.

• The same code can come with a different name in each list (full in one, abbreviated in the other). Use the name from the list of the method you are going to pay with.
• The response is served from cache and, if the catalog does not answer, we return a local copy: this endpoint does not fail.
• For your app’s bank picker: shortName for the UI, name for receipts.
• Omitting method —or sending any other query parameter— returns 400 validation_failed.

2 · Gather the data for the method

	pago_movil	transferencia
fullName	✅	✅
nationalId	✅	✅
bankCode	✅	✅
phone	✅ (it is the destination)	optional
accountNumber	—	✅

3 · Register the beneficiary

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. Bank transfer (the phone number is optional)

   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
   }

Registration is idempotent on (national ID, bank, method): created: false means it already existed with that data and we return the same id.

Validation rules

They are checked before spending a call to the payment network. All of them return 400 validation_failed, and error.meta.field tells you which one failed.

Field	Rule	Valid example
fullName	At least 3 characters. Exactly as the destination bank has it	María Gómez
nationalId	V, E, J, G or P + 6 to 9 digits. Normalized to uppercase, without dots or dashes	V12345678
bankCode	Exactly 4 digits	0134
accountNumber	Digits only, 16 to 20 — in Venezuelan practice they are 20 — and it must start with the bankCode	01340000123456789012
phone	Exactly 04 + 9 digits	04141234567
—	At least one of accountNumber or phone is required

If the account does not start with the bank code, the (Spanish) message is: El número de cuenta pertenece al banco 0102, no al 0134 (“The account number belongs to bank 0102, not 0134”).

The most frequent bank rejection is about ownership

The name or national ID does not match the holder of that account or that phone number. Send fullName exactly as the destination bank has it, not as you have it. It later shows up as reason: "beneficiary_mismatch" on the payout.

Look up and list

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"

The list is cursor-paginated. payout_count, last_success_at and last_failure_reason are the beneficiary’s history.

error.code	HTTP	When
beneficiary_not_found	404	It does not exist, or it belongs to another program
beneficiary_blocked	422	It is blocked. It cannot be read or paid out to

Inline beneficiary

POST /payouts accepts the beneficiary block with the same fields, so you do not spend two calls per person:

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"}}'

The same idempotent registration applies, so you do not duplicate rows: the response carries the beneficiaryId that was used or created.

Next step

Pay out bolívares.