Skip to content
Bolívar Connect

The flow, step by step

A capture of a payout executed end to end against the paying bank’s test environment. Bs 1,100.00 went out via pago móvil and Bs 1,871.60 via bank transfer, to different Venezuelan banks, and the money was deducted from the balance. The bodies are the ones that went over the wire, with only the identifiers replaced by their test equivalents; the latencies are those of that run.

These are ten calls in the order a connected fintech makes them: look up banks, quote, pay out, check at the bank, retry without paying twice, quote in foreign currency, pay out through another method, look up the payment, list the day and check the balance.

The request and response bodies are shown exactly as they traveled, so some API messages inside them are in Spanish.

Real trace·10 calls·3393 ms wall clock
Pago móvil
Bs 1,100.00 submitted
Bank transfer
Bs 1,871.60 submitted
Closing balance
Bs 499,996,998.50
Captured
September 1, 2026 at 4:18 PM UTC

Step 1 of 10

GET/v1/payouts/banks?method=pago_movil342 ms

1. Look up the banks the method accepts

Returns 31 banks for pago móvil. The first four are shown below; the rest come in the same list.

Response

{
  "method": "pago_movil",
  "data": [
    {
      "code": "0001",
      "name": "Banco Central de Venezuela",
      "shortName": "BCV"
    },
    {
      "code": "0102",
      "name": "Banco de Venezuela S.A.C.A. Banco Universal",
      "shortName": "Banco de Venezuela"
    },
    {
      "code": "0104",
      "name": "Venezolano de Crédito, S.A. Banco Universal",
      "shortName": "Venezolano de Crédito"
    },
    {
      "code": "0105",
      "name": "Banco Mercantil, C.A. Banco Universal",
      "shortName": "Mercantil"
    }
  ]
}

The bank transfer list is shorter. That is why `method` is required.

POST/v1/quotes9 ms

2. Quote an exact amount in bolívares

You fix `deliver` and the beneficiary receives exactly that amount; the fee is added on top in `spend`. With no conversion, `rate` comes back null.

Request body

{
  "deliver": {
    "asset": "BS",
    "amount": 110000
  }
}

Response

{
  "id": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "fixed": "deliver",
  "spend": {
    "asset": "BS",
    "amount": "111100"
  },
  "deliver": {
    "asset": "BS",
    "amount": "110000"
  },
  "fee": {
    "asset": "BS",
    "amount": "1100"
  },
  "rate": null,
  "status": "open",
  "expires_at": "2026-09-01T16:18:59.096Z",
  "created_at": "2026-09-01T16:17:59.096Z"
}
POST/v1/payouts1331 ms

3. Pay out via pago móvil

The beneficiary details travel in the same call: no need to register them first. The phone number is required.

Headers

{
  "Idempotency-Key": "nomina-2026-09-01-0042"
}

Request body

{
  "quoteId": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "method": "pago_movil",
  "beneficiary": {
    "fullName": "Maria Rodriguez",
    "nationalId": "V12345678",
    "bankCode": "0102",
    "phone": "04241111111"
  },
  "sender": {
    "nationalId": "V34567890",
    "firstName": "Ana",
    "lastName": "Rivas",
    "phone": "04143333333",
    "email": "ana@ejemplo.com"
  }
}

Response

{
  "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "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": "110000",
  "feeAmount": "1100",
  "totalDebited": "111100",
  "method": "pago_movil",
  "methodRequested": "pago_movil",
  "methodChanged": false,
  "beneficiaryId": "c8be416d-ceb1-4529-873c-74bce8606894",
  "beneficiary": {
    "fullName": "Maria Rodriguez",
    "nationalId": "V12345678",
    "bankCode": "0102",
    "instrument": "pago_movil"
  }
}

The status is `submitted`, not `settled`: the bank accepted the order and delivers afterwards.

GEThttps://api.disperador/api/v1/transactions/{externalId}210 ms

4. The transaction exists at the bank

Looked up in the paying bank's API by OUR reference. It is the only check in the walkthrough that does not go through our code.

Response

{
  "_id": "6a96fab84d4009d23974aa14",
  "token": {
    "name": "USDT-POLYGON",
    "symbol": "USDT"
  },
  "chain": "Polygon Mainnet",
  "transactionType": "pagoMovilWithdraw",
  "amount": 1.16629,
  "fiatAmount": 1100,
  "status": "en progreso",
  "exchangeRate": {
    "currencyFrom": {
      "name": "USDT",
      "symbol": "USDT"
    },
    "currencyTo": {
      "name": "Bolivar",
      "symbol": "VES"
    },
    "exchangeRateNumber": 943.162
  },
  "senderData": {
    "identificationNumber": "V34567890",
    "name": "Ana",
    "lastName": "Rivas",
    "phoneNumber": "04143333333",
    "email": "ana@ejemplo.com"
  },
  "externalId": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "createdAt": "2026-09-01T16:18:00.435Z",
  "updatedAt": "2026-09-01T16:18:00.585Z",
  "pagoMovilData": {
    "phoneNumber": "04241111111",
    "identificationNumber": "V12345678",
    "beneficiaryName": "Maria Rodriguez",
    "bank": {
      "name": "Banco de Venezuela",
      "code": "0102"
    }
  }
}

It delivers exactly Bs 1,100. The bank charges in foreign currency (1.16629 USDT), but that is our business, not yours.

POST/v1/payouts4 ms

5. Resend the same request after a timeout

With the same Idempotency-Key. It returns the original payment instead of creating another one, so a retry from your queue never pays twice.

Headers

{
  "Idempotency-Key": "nomina-2026-09-01-0042"
}

Request body

{
  "quoteId": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "method": "pago_movil",
  "beneficiary": {
    "fullName": "Maria Rodriguez",
    "nationalId": "V12345678",
    "bankCode": "0102",
    "phone": "04241111111"
  },
  "sender": {
    "nationalId": "V34567890",
    "firstName": "Ana",
    "lastName": "Rivas",
    "phone": "04143333333",
    "email": "ana@ejemplo.com"
  }
}

Response

{
  "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "asset": "BS",
  "amount": "110000",
  "method": "pago_movil",
  "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.",
  "feeAmount": "1100",
  "beneficiary": {
    "bankCode": "0102",
    "fullName": "Maria Rodriguez",
    "instrument": "pago_movil",
    "nationalId": "V12345678"
  },
  "totalDebited": "111100",
  "bankReference": null,
  "beneficiaryId": "c8be416d-ceb1-4529-873c-74bce8606894",
  "methodChanged": false,
  "methodRequested": "pago_movil"
}

Same `id` as the first call.

POST/v1/quotes9 ms

6. Or quote in dollars, if your balance is in foreign currency

Here you fix `spend` and we return what arrives. SAME response shape as above: only which side you fixed (`fixed`) changes, and `rate` is now filled in.

Request body

{
  "spend": {
    "asset": "USD",
    "amount": 5000
  },
  "deliver": {
    "asset": "BS"
  }
}

Response

{
  "id": "477174b9-a9bb-4f31-8407-3661ae29bffe",
  "fixed": "spend",
  "spend": {
    "asset": "USD",
    "amount": "5000"
  },
  "deliver": {
    "asset": "BS",
    "amount": "187160"
  },
  "fee": {
    "asset": "BS",
    "amount": "1890"
  },
  "rate": {
    "value": "37.81",
    "market": "38",
    "spread_bps": 50
  },
  "status": "open",
  "expires_at": "2026-09-01T16:19:00.652Z",
  "created_at": "2026-09-01T16:18:00.652Z"
}

To pay out bolívares it is usually better to fix `deliver`: with this one the delivered amount comes from the rate, you do not choose it.

POST/v1/payouts1477 ms

7. Pay out via bank transfer

Same endpoint, different method. What identifies the beneficiary changes: a 20-digit account instead of a phone number, although the phone is still required.

Headers

{
  "Idempotency-Key": "nomina-2026-09-01-0043"
}

Request body

{
  "quoteId": "477174b9-a9bb-4f31-8407-3661ae29bffe",
  "method": "transferencia",
  "beneficiary": {
    "fullName": "Juan Perez",
    "nationalId": "V23456789",
    "bankCode": "0108",
    "accountNumber": "01080000000000000002",
    "phone": "04141111111"
  },
  "sender": {
    "nationalId": "V45678901",
    "firstName": "Ana",
    "lastName": "Rivas",
    "phone": "04142222222",
    "email": "ana@ejemplo.com"
  }
}

Response

{
  "id": "a4f320a2-5964-49aa-8628-97a6aa418bd2",
  "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": "187160",
  "feeAmount": "1890",
  "totalDebited": "189050",
  "method": "transferencia",
  "methodRequested": "transferencia",
  "methodChanged": false,
  "beneficiaryId": "ae3c8182-d543-46e9-aad0-873da3eeb196",
  "beneficiary": {
    "fullName": "Juan Perez",
    "nationalId": "V23456789",
    "bankCode": "0108",
    "instrument": "transferencia"
  }
}
GET/v1/payments/71103d0a-4e59-4a9a-b3c1-de6917b8bbc15 ms

8. Look up a specific payment

With its status history. `bank_reference` is the receipt the beneficiary asks for, and it appears on settlement.

Response

{
  "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "tenant_id": "1254fc3f-fbe5-46cf-adcc-8428b5c397a7",
  "customer_id": null,
  "beneficiary_id": "c8be416d-ceb1-4529-873c-74bce8606894",
  "status": "submitted",
  "status_reason": "payout_accepted_async",
  "source_asset": "BS",
  "source_amount": "111100",
  "payout_asset": "BS",
  "payout_amount": "110000",
  "fee_amount": "1100",
  "method": "pago_movil",
  "counterparty": "04241111111",
  "bank_reference": null,
  "quote_id": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "ledger_transaction_id": "7d6ec749-c75a-48eb-af5c-9282bb5441d7",
  "compensated": false,
  "settled_at": null,
  "created_at": "2026-09-01T16:17:59.106Z",
  "updated_at": "2026-09-01T16:18:00.424Z",
  "events": [
    {
      "from_status": null,
      "to_status": "submitted",
      "reason": "ledger_committed",
      "actor": "api",
      "metadata": {
        "quoteId": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
        "beneficiaryId": "c8be416d-ceb1-4529-873c-74bce8606894",
        "ledgerTransactionId": "7d6ec749-c75a-48eb-af5c-9282bb5441d7"
      },
      "created_at": "2026-09-01T16:17:59.106Z"
    },
    {
      "from_status": "submitted",
      "to_status": "submitted",
      "reason": "payout_accepted_async",
      "actor": "api",
      "metadata": {
        "methodUsed": "pago_movil",
        "methodRequested": "pago_movil"
      },
      "created_at": "2026-09-01T16:18:00.424Z"
    }
  ]
}
GET/v1/payments?limit=52 ms

9. List its transactions

Accepts `from`, `to`, `status` and `beneficiaryId`. The date range measures SETTLEMENT, not creation: a payment in flight is not part of today's close.

Response

{
  "data": [
    {
      "id": "a4f320a2-5964-49aa-8628-97a6aa418bd2",
      "customer_id": null,
      "beneficiary_id": "ae3c8182-d543-46e9-aad0-873da3eeb196",
      "status": "submitted",
      "status_reason": "payout_accepted_async",
      "source_asset": "USD",
      "source_amount": "5000",
      "payout_asset": "BS",
      "payout_amount": "187160",
      "fee_amount": "1890",
      "method": "transferencia",
      "bank_reference": null,
      "settled_at": null,
      "created_at": "2026-09-01T16:18:00.656Z"
    },
    {
      "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
      "customer_id": null,
      "beneficiary_id": "c8be416d-ceb1-4529-873c-74bce8606894",
      "status": "submitted",
      "status_reason": "payout_accepted_async",
      "source_asset": "BS",
      "source_amount": "111100",
      "payout_asset": "BS",
      "payout_amount": "110000",
      "fee_amount": "1100",
      "method": "pago_movil",
      "bank_reference": null,
      "settled_at": null,
      "created_at": "2026-09-01T16:17:59.106Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
GET/v1/treasury/position?asset=BS4 ms

10. Check how much balance is left

Each payout deducts the delivered amount plus the fee.

Response

{
  "tenantId": "1254fc3f-fbe5-46cf-adcc-8428b5c397a7",
  "asset": "BS",
  "prefundingBalance": "49999699850",
  "platformRevenueFromTenant": "2990",
  "creditEnabled": true,
  "creditDrawn": "0",
  "creditLimit": null,
  "creditAvailable": null
}

What is worth a second look

Section titled “What is worth a second look”
  • Step 3 returns submitted, not settled. That is the normal outcome on the payment network. Step 4 confirms it from the paying bank’s API, where the status is “in progress”. See payment states.
  • Step 5 repeats the POST /v1/payouts with the same Idempotency-Key and returns the original payment, with the same id, in 4 ms. See idempotency.
  • Steps 2 and 6 are the two ways to quote and return the same shape. Step 2 fixes deliver; step 6 fixes spend. Between the two bodies, fixed changes and in step 6 rate is filled in; the field names do not change. See quote in bolívares.
  • The only reference for the transfer is bank_reference, the receipt the beneficiary sees at their bank.

Reproducing it

Section titled “Reproducing it”

These are the calls documented in your first payout, with an sk_test_… key and the data from the test environment.