Your first payout

No API key yet?

Get one in a minute: enter your company email, you receive a link and when you open it you see your test key (sk_test_…). It does not move real money.

Get my test key

Five calls to deliver Bs 50,000.00 via pago móvil, runnable as-is against the test environment.

Variables used by every example

BASE=http://localhost:3000      # or https://api.your-domain.com
KEY=sk_test_...                 # get it at bolivarconnect.com/en/api-keys

1. Confirm which key you are calling with

   curl -s $BASE/v1/tenant/me -H "x-api-key: $KEY"

   200 OK

   {
     "tenantId": "3f1a0c22-9b41-4a77-8f0e-6d2c5b7a1e34", "name": "Fintech Ejemplo",
     "mode": "test",
     "scopes": ["quotes:write", "beneficiaries:write", "beneficiaries:read",
                "payments:write", "payments:read", "treasury:read",
                "events:read", "events:write"],
     "apiKeyId": "5c9d2b70-1f44-4c8e-9a3b-2e7f0d5a6b18", "isPlatform": false
   }

   mode tells you whether you are moving real money. See authentication.

2. Get the bank catalog for the method you will use

   curl -s "$BASE/v1/payouts/banks?method=pago_movil" -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": "0108", "name": "Banco Provincial, S.A. Banco Universal",      "shortName": "Banco Provincial - BBVA" },
       { "code": "0134", "name": "Banesco Banco Universal S.A.C.A.",            "shortName": "Banesco" }
     ]
   }

   `method` is required, and the two lists do not match

   31 banks reachable via pago móvil and 24 via bank transfer. Without method, 400 validation_failed. See beneficiaries.

3. Quote the exact amount in bolívares

   curl -s $BASE/v1/quotes \
     -H "x-api-key: $KEY" -H 'content-type: application/json' \
     -d '{"deliver":{"asset":"BS","amount":5000000}}'

   201 Created

   {
     "id": "70ec44b5-c1df-45b1-86fe-8f92c3959689", "fixed": "deliver",
     "spend":   { "asset": "BS", "amount": "5050000" },
     "deliver": { "asset": "BS", "amount": "5000000" },
     "fee":     { "asset": "BS", "amount":   "50000" },
     "rate": null, "status": "open",
     "expires_at": "2026-08-31T20:22:36.022Z", "created_at": "2026-08-31T20:21:36.022Z"
   }

   deliver is the Bs 50,000.00 the beneficiary receives, fee the Bs 500.00 fee (an example: your fee depends on your commercial agreement and your volume; see GET /v1/treasury/volume-fee) and spend the Bs 50,500.00 debited from you. Amounts are in minor units: BS has 2 decimals, so 5000000 = Bs 50,000.00. See amounts.

   If you fund in foreign currency, you fix spend instead of deliver and the response carries the same fields with rate filled in. See quoting.

   The quote expires in ~60 seconds

   It is single use. Quote right before paying out. Using it twice returns 409 quote_already_consumed; using it after it expired, 422 quote_expired. Quoting is free: quote as many times as you like and consume the latest one.

4. Pay out

   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",
          "beneficiary":{"fullName":"María Gómez","nationalId":"V12345678",
                         "bankCode":"0138","phone":"04141234567"},
          "sender":{"nationalId":"V18234112","firstName":"Ana","lastName":"Pérez",
                    "phone":"04241234567","email":"ana@example.com"}}'

   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",
     "beneficiary": { "fullName": "María Gómez", "nationalId": "V12345678",
                      "bankCode": "0138", "instrument": "pago_movil" }
   }

   The API’s message texts are in Spanish; program against status and error.code, never against the message.

   Four fields that break integrations if you overlook them:

   • Idempotency-Key. A network retry without it pays twice. See idempotency.
   • beneficiary.phone. Required for pago_movil, where it is the destination. Optional for transferencia.
   • beneficiary.fullName. A first and last name that look real: a placeholder ends up failed. The test beneficiaries come without an account holder, and the sandbox does not check ownership; production does.
   • sender. Who orders the transfer. If you do not send it, it is derived from customerId or from your program’s default sender; with neither, the payment fails before it goes out.

   Watch the status: `submitted`, not `settled`

   The payment network is asynchronous: submitted is the normal outcome. If your code requires settled here, it works in the sandbox and breaks in production. See payment states.

5. Receive the outcome

   The result arrives by webhook, once:

   POST to your webhookUrl

   { "id": "40545", "eventType": "payment.settled", "attempt": 1,
     "payload": { "paymentId": "89920401-26da-4f69-b57d-bc20e0366ce2",
                  "asset": "BS", "amount": "5000000", "method": "pago_movil",
                  "bankReference": "012345678901" } }

   Verify the HMAC signature and deduplicate on id: delivery is at-least-once. See webhooks. You can also look it up:

   curl -s $BASE/v1/payments/89920401-26da-4f69-b57d-bc20e0366ce2 -H "x-api-key: $KEY"

   200 OK (trimmed)

   {
     "id": "89920401-26da-4f69-b57d-bc20e0366ce2", "status": "settled",
     "payout_asset": "BS", "payout_amount": "5000000", "fee_amount": "50000",
     "method": "pago_movil", "bank_reference": "012345678901",
     "settled_at": "2026-08-31T19:06:44.120Z",
     "events": [
       { "to_status": "submitted", "reason": "ledger_committed",    "actor": "api" },
       { "to_status": "submitted", "reason": "payout_accepted_async", "actor": "api" },
       { "to_status": "settled",   "reason": "resolved_by_reaper",  "actor": "reaper" }
     ]
   }

   bank_reference is the receipt the beneficiary sees at their bank.

What to read next

If you are going to…	Read
see these calls actually executed	The flow, step by step
understand which objects the API handles	How it works
pay to an account instead of a phone	Register a beneficiary
build your user’s screen	Track the payment
reconcile the day	Reconcile a day
put this into production	Before production

API conventions

Topic	In one line
Base URL	https://api.your-domain.com/v1 · testing: http://localhost:3000/v1
Authentication	x-api-key header. sk_test_… keys do not move real money
Amounts	Integers in minor units. Bs 50,000.00 is 5000000. Number in the request, string in the response
Idempotency	Idempotency-Key on every payout, always
Pagination	Cursor-based (limit + cursor), never offset. Maximum 100
Errors	Program against error.code, never against the message
Webhooks	Signed with HMAC-SHA256. At-least-once delivery: deduplicate on id
Minimum per transaction	~Bs 925. Details
Cap per transaction	Pago móvil: Bs 100,000.00. Bank transfer: Bs 500,000.00