Ir al contenido
Bolívar Connect

Register a payout beneficiary

POST/beneficiariesProbar

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

POST
/beneficiaries
curl --request POST \
  --url http://localhost:3000/v1/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "fullName": "María Gómez", "nationalId": "V12345678", "bankCode": "0134", "accountNumber": "01340000123456789012", "phone": "04141234567" }'

Scope beneficiaries:write. Registration is idempotent by (national ID, bank, instrument): sending the same data again returns the same beneficiary (created: false) instead of duplicating it.

phone is required for pago_movil, where it is the destination. For transferencia you need accountNumber, and phone is optional.

It is validated before spending a call to the payment network:

  • national ID or RIF V/E/J/G/P + 6 to 9 digits (V12345678);
  • a 4-digit bankCode, from the catalog of the instrument you will use (GET /payouts/banks?method=…);
  • accountNumber digits only, 16 to 20 —in Venezuelan practice they are 20— and it starts with the bankCode;
  • phone as 04XXXXXXXXX (required to pay out by pago móvil; optional for bank transfer).

The most common rejection by a Venezuelan bank is that the name or national ID don’t match the holder of that account or phone: send fullName exactly as the destination bank has it.

Authorizations

Sección titulada «Authorizations»

Request Bodyrequired

Sección titulada «Request Bodyrequired»
Media typeapplication/json

phone es necesario para dispersar por pago_movil (es el destino); accountNumber, para transferencia, donde el phone es opcional.

El alta exige al menos uno de los dos campos. Un beneficiario sin phone sólo cobra por transferencia; si se le dispersa por pago móvil, falla con beneficiary_missing_phone.

object
fullName
required

Nombre del titular TAL COMO lo tiene el banco destino

string
nationalId
required

Cédula o RIF: V/E/J/G/P + 6 a 9 dígitos

string
bankCode
required

Banco destino, 4 dígitos

string
accountNumber

Sólo dígitos, de 16 a 20 (en la práctica venezolana, 20), y debe empezar por el bankCode. Necesario para transferencia.

string
nullable
phone

Móvil del beneficiario, formato 04XXXXXXXXX. Obligatorio para pago móvil; opcional en transferencia.

string
nullable
asset

Decimales: BS y USD 2; USDT y USDC 6 (1000000 = 1 USDT).

string
Allowed values: BS USD USDT USDC VESC
country
string
Examples

Abono en cuenta (transferencia) — el móvil también hace falta

{
  "fullName": "María Gómez",
  "nationalId": "V12345678",
  "bankCode": "0134",
  "accountNumber": "01340000123456789012",
  "phone": "04141234567"
}

Responses

Sección titulada «Responses»

201

Sección titulada «201»

Beneficiario (nuevo o ya existente)

Media typeapplication/json
object
id
string format: uuid
full_name
string
national_id
string
bank_code
string
account_number
string
nullable
phone
string
nullable
asset

Decimales: BS y USD 2; USDT y USDC 6 (1000000 = 1 USDT).

string
Allowed values: BS USD USDT USDC VESC
country
string
status
string
Allowed values: active blocked
payout_count

Cuántas dispersiones le han llegado bien. Señal antifraude.

integer
last_success_at
string format: date-time
nullable
last_failure_reason
string
nullable
created_at
string format: date-time
created

False si ya existía con esos datos

boolean
Example
{
  "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
}

400

Sección titulada «400»

Error con código estable

Media typeapplication/json
object
error
object
meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object
key
additional properties
any
type
string
Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error
code

Código ESTABLE. Programa contra esto.

string
message
string
request_id
string
Example
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

401

Sección titulada «401»

Error con código estable

Media typeapplication/json
object
error
object
meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object
key
additional properties
any
type
string
Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error
code

Código ESTABLE. Programa contra esto.

string
message
string
request_id
string
Example
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

403

Sección titulada «403»

Error con código estable

Media typeapplication/json
object
error
object
meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object
key
additional properties
any
type
string
Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error
code

Código ESTABLE. Programa contra esto.

string
message
string
request_id
string
Example
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}