Pay out bolívares

One call. It delivers the quoted bolívares to the beneficiary, at their own bank, through the method you ask for.

curl -s $BASE/v1/payouts \
  -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -H 'Idempotency-Key: payout-2026-0001' \
  -d '{"quoteId":"70ec44b5-c1df-45b1-86fe-8f92c3959689","method":"pago_movil",
       "beneficiaryId":"8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
       "sender":{"nationalId":"V18234112","firstName":"Ana","lastName":"Pérez",
                 "phone":"04241234567","email":"ana@example.com"}}'

What you send

Field	Required	What it is
quoteId	yes	Fixes the amount in Bs and our fee. There is no amount field in this call
method	yes	pago_movil or transferencia
beneficiaryId	one of the two	An already registered beneficiary
beneficiary	one of the two	Their details inline
sender	in practice, yes	Who orders the transfer. See below
methodPolicy	no	preferred (default) or strict. See below
customerId	no	Which of your users it belongs to. For your traceability and for per-user limits
reference	no	Payment concept, 3 to 30 characters. See below

Without `Idempotency-Key` a network retry pays twice

The Idempotency-Key header carries a key that is unique per operation — your own transaction id works. With the same key and the same body we return the original response without paying out again. See idempotency.

The two methods

Pago móvil

It arrives at the beneficiary’s phone number. It needs bank, mobile number, national ID and name.

curl -s $BASE/v1/payouts -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -H 'Idempotency-Key: payout-2026-0002' \
  -d '{"quoteId":"'$QUOTE'","method":"pago_movil",
       "beneficiary":{"fullName":"José Marcano","nationalId":"V18234112",
                      "bankCode":"0138","phone":"04141234567"},
       "sender":{"nationalId":"V12345678","firstName":"Ana","lastName":"Pérez",
                 "phone":"04241234567","email":"ana@example.com"}}'

Cap per transaction: Bs 100,000.00 (10000000), set by the receiving bank for pago móvil. See limits.

Bank transfer

A credit to the beneficiary’s account. It needs bank, 20-digit account —starting with the bank code—, national ID, name and the mobile number too.

curl -s $BASE/v1/payouts -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -H 'Idempotency-Key: payout-2026-0003' \
  -d '{"quoteId":"'$QUOTE'","method":"transferencia",
       "beneficiary":{"fullName":"María Gómez","nationalId":"V12345678",
                      "bankCode":"0134","accountNumber":"01340000123456789012",
                      "phone":"04141234567"},
       "sender":{"nationalId":"V18234112","firstName":"Ana","lastName":"Pérez",
                 "phone":"04241234567","email":"ana@example.com"}}'

The catalog of banks reachable by bank transfer is shorter than the pago móvil one: 24 versus 31.

What comes back

201 Created

{
  "id": "89920401-26da-4f69-b57d-bc20e0366ce2", "status": "submitted",
  "message": "La red de pago aceptó el envío y todavía no lo ha liquidado. Se confirmará por webhook (payment.settled); no lo reintentes con otra Idempotency-Key.",
  "bankReference": null, "asset": "BS", "amount": "5000000",
  "feeAmount": "50000", "totalDebited": "5050000",
  "method": "pago_movil", "methodRequested": "pago_movil", "methodChanged": false,
  "beneficiaryId": "8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
  "reference": null,
  "beneficiary": { "fullName": "María Gómez", "nationalId": "V12345678",
                   "bankCode": "0138", "instrument": "pago_movil" }
}

Field	What it is
amount	What the beneficiary receives: Bs 50,000.00
feeAmount	Our fee: Bs 500.00
totalDebited	What came off your balance: Bs 50,500.00
bankReference	The receipt the beneficiary will see. null until the payment network settles
method vs methodRequested	Where it went out vs. where you asked it to go out
methodChanged	true if the method was switched
reference	The payment concept you sent, already cleaned up. null if you sent none
message	A human-readable explanation, in Spanish. Do not parse it

The four outcomes

POST /payouts responds 201 whenever the operation was processed, even when it failed: the outcome is in status, not in the HTTP code.

status	What happened	What you do
submitted	The payment network accepted it and is settling. This is the normal outcome	Do not retry. Wait for the webhook
settled	Settled: the beneficiary has their Bs	Nothing
failed	No payment network accepted it. The entry has already been reversed: you are not charged anything	Fix it and retry with another quote
unknown	The payment network did not confirm and we do not know whether it paid	NEVER retry. It resolves on its own

`settled` is NOT the usual response

Delivery is asynchronous. if (status === 'settled') works against the sandbox —where it settles on the spot— and breaks in production. Build on the webhook, not on this response. See payment states.

When the status is failed

The response carries reason, and feeAmount comes as "0" because the entry was fully reversed.

201 Created — payout rejected

{
  "id": "89920401-26da-4f69-b57d-bc20e0366ce2", "status": "failed",
  "reason": "beneficiary_missing_phone",
  "asset": "BS", "amount": "5000000", "feeAmount": "0",
  "beneficiaryId": "8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
  "beneficiary": { "fullName": "María Gómez", "nationalId": "V12345678",
                   "bankCode": "0134", "instrument": "pago_movil" }
}

`reason` is not `error.code`

The payment network’s rejection reasons travel in the reason field of a 201 response, not in an error envelope. They are a different taxonomy from HTTP errors.

The most frequent are beneficiary_missing_phone (mobile number missing for pago móvil), beneficiary_mismatch, sender_required, amount_below_minimum and no_route. Full catalog in errors; what to do with each one, in when something fails.

The sender (sender)

Who orders the transfer. It is obtained in three ways, in this order: the sender block of the request; the user referenced by customerId, if they have an ID document, name, mobile number and email; your program’s default sender.

If none of the three exists, the payout fails before it goes out

No sender is made up: 201 with status: "failed" and reason: "sender_required".

"sender": { "nationalId": "V18234112", "firstName": "Ana", "lastName": "Pérez",
            "phone": "04241234567", "email": "ana@example.com", "nationality": "VEN" }

Field	Required	Format
nationalId	yes	Venezuelan: V, E or J + up to 9 digits. Foreign: 5 to 20 alphanumeric characters, with no Venezuelan letter in front
firstName · lastName	yes	At least 2 characters
phone	yes	Venezuelan mobile (0412/0414/0416/0424/0426): 04141234567, +584141234567 and 4141234567 are accepted and normalized to 04XXXXXXXXX. Or an international E.164 number (+, country code and number, 8 to 15 digits, other than +58), e.g. +34612345678. Valid for any nationality. A Venezuelan landline is rejected
email	yes	—
nationality	no	ISO 3166-1 alpha-3. Absent means VEN, and it decides which format nationalId must follow

If you send the block, all its fields are required except nationality. Errors arrive as 400 validation_failed with error.meta.field (e.g. sender.phone) and error.meta.origen (request, customer or env), which tells you which of the three paths failed.

A sender living abroad sends their number as is, in E.164:

"sender": { "nationalId": "V18234112", "firstName": "Ana", "lastName": "Pérez",
            "phone": "+34 612 345 678", "email": "ana@example.com" }

Spaces, dashes, dots and parentheses are stripped and +34612345678 is stored. If no available payment network accepts an international phone number, the payout comes out failed with reason: "sender_phone_unsupported" and the entry reversed.

The payment concept (reference)

A text from you or your user that reaches the beneficiary’s bank as the payment concept, when the payment network supports it. It is optional: if you do not send it, everything stays as usual.

"reference": "Nómina octubre 0007"

• 3 to 30 characters, counted after trimming extra spaces and control characters. Outside that range: 400 validation_failed, before any money is touched.
• It is stored on the payment and comes back in the response, in GET /payments/{id}, in the statement (GET /payments) and in the payment.* webhooks.
• If the payment network delivering the payment has no concept field, the payment goes out anyway, without the concept: it never fails because of that.
• It is not bankReference (the receipt assigned by the bank) nor the Idempotency-Key.

If the requested method is not available

methodPolicy	Behavior
preferred (default)	It is delivered through the other method if needed, and we tell you with methodChanged: true
strict	Only the requested method. If it is not possible, the payout fails and the entry is reversed

Went out by bank transfer after pago móvil was requested

{ "status": "submitted", "method": "transferencia",
  "methodRequested": "pago_movil", "methodChanged": true }

Use strict when the method is part of what you promised your user.

Errors before reaching the payment network

These are HTTP errors: the payout was never created.

error.code	HTTP	When
validation_failed	400	Both beneficiaryId and beneficiary are missing; the quote cannot be used to pay out; the quote’s asset does not match the beneficiary’s; the sender is wrong
beneficiary_not_found	404	The beneficiaryId is not yours or does not exist
beneficiary_blocked	422	The beneficiary is blocked
beneficiary_instrument_missing	422	No phone number for pago móvil, or no account for bank transfer
quote_not_found	404
quote_already_consumed	409	Another payout already used that quote
quote_expired	422	Request a new one
limit_exceeded	422	error.meta says which limit and by how much
insufficient_tenant_funds	422	Your balance is not enough (only if you operate prefunded)
idempotency_key_reused	409	Same key, different body
no_route_available	503	There is no payment network for that country/asset/method

Next step

Track the payment to its outcome.