Balances, holds and payouts
What is available, what waits for bank confirmation and why, how automatic settlement works, what payouts cost, and how to reconcile it all.
The parts of a balance
Each currency (bolívares, USDT, USDC, Colombian pesos) has its own balance. Inside each one, your money is in one of these states:
| State | What it is | Can be paid out? |
|---|---|---|
| Available | Released money you can withdraw, pay out or convert | Yes |
| Awaiting bank confirmation (Bs only) | Bolívar payments the bank has not confirmed yet (unconfirmedVes) | Not yet — it becomes available on its own once the bank confirms it |
| Held | A balance hold VEX Pay set for your account, if any (none by default) | Not yet — it becomes available on its own |
| Reserve (Bs only) | A safety buffer set by VEX Pay for your account, if any | No |
| Pending payout | Reserved by payouts that are on their way | Already leaving |
curl "${API_URL}/v1/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
# availableVes = ledgerNetVes − reserveVes − heldVes − unconfirmedVescurl "${API_URL}/v1/crypto/balances" --header "x-api-key: ${VEXPAY_API_KEY}"
# each: available, held, nextReleaseAt, pendingPayout (USDT also availableUsdt, heldUsdt)curl "${API_URL}/v1/cop/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
# availableCop, heldCop, nextReleaseAt, pendingPayoutCopBank confirmation (no 24h hold)
There is no time-based hold by default (balanceHoldHours is 0). A bolívar payment counts toward availableVes once the bank confirms the money arrived; until then it is in unconfirmedVes. Nothing needs to happen on your side and no webhook is sent when it clears. USDT and pesos are available as soon as they are credited, except USDT bought (converted) with bolívares still awaiting bank confirmation: it shows as held (heldUsdt, with no nextReleaseAt) and becomes available once the bank confirms every payment it was paid from.
| Movement | Waits for the bank? |
|---|---|
| Completed bolívar payments, net of the VEXPay fee | Yes — until the bank confirms the payment |
| Bolívar payments the bank cannot find | Yes — they stay out of available until VEXPay resolves them |
| USDT, USDC and peso payments | No |
| Money coming back: failed payouts, canceled conversions, fee reversals | No — it returns exactly as it left |
| While bolívares await the bank, you can… | Rule |
|---|---|
| Pay out to your bank or a seller | No — payouts spend bank-confirmed money only |
| Convert to USDT | Yes |
| Transfer to a seller | Yes |
| Refund or reverse the payment | Yes, when your balance covers it |
Automatic settlement
In live mode, every 15 minutes VEXPay sends your available bolívares to your verified payout account as an instant payout — two when your balance arrived through more than one bank, since each payout leaves in one bank transfer. It goes through the same path as POST /v1/payouts/instant: your instant payout fee applies, the payout appears in GET /v1/payouts, and you receive the usual payout.* webhooks.
| Detail | Value |
|---|---|
| What is sent | All of availableVes, in at most two payouts per run; each one is sent once it reaches the minimum (settlement.minimumVes, Bs 100.00 by default), and a smaller part waits for a later run |
| How to recognize it | externalRef starts with auto_settle_; the bank concept reads “Liquidacion VEX Pay” |
| If it fails | The money returns to your balance and the next run tries again |
| No verified payout account | Nothing is sent; your balance stays until you add and verify one |
| Your status | settlement on GET /v1/balance: enabled and status (for example active, no_payout_account, opted_out, test_mode) |
You can still withdraw yourself between runs with POST /v1/payouts/instant. Accounts that pay sellers or disbursements from their balance can ask VEXPay to turn automatic settlement off.
When a payout is refused
A payout larger than the available part answers 422 insufficient_balance with the amounts you need to decide what to do:
{
"error": "insufficient_balance",
"availableVes": "3000.00",
"requestedVes": "4000.00",
"heldVes": "0.00",
"unconfirmedVes": "4342.50",
"nextReleaseAt": null,
"maxPayoutVes": "3000.00"
}- Pay out at most the available amount now.
unconfirmedVesbecomes available as the bank confirms each payment. - A Bs payout is sent as one bank transfer and is never split, so the most a single payout can take is
maxPayoutVes, which can be lower thanavailableVes. Send that amount, then the rest in a second payout. - Do not retry in a loop — nothing changes until the bank confirms a payment or new money arrives.
- USDT payouts answer the same way with
availableUsdt,heldUsdtandnextReleaseAt; ops COP payouts withavailableCopandheldCop.
What payouts cost
| Payout | Fee |
|---|---|
| To your own bank account (instant withdrawal) | Your bolívar percentage on the amount withdrawn |
| To your verified sellers | Free (a seller payout fee may apply by agreement) |
| USDT to an external wallet | The network’s payout fee, shown by GET /v1/crypto/networks |
| USDC to an external wallet | The network’s payout fee, shown by GET /v1/crypto/networks |
| To one of your own deposit addresses | Free — settled inside VEXPay |
GET /v1/crypto/networks returns the exact payout fee per network before you send. The fee is reserved together with the amount and returned if the payout fails.
Reconcile it
- Walk the movements
GET /v1/balance/transactions lists every bolívar movement. The sum equals ledgerNetVes.
- Account for bank confirmation
Sum minus reserveVes minus heldVes minus unconfirmedVes equals availableVes. Automatic settlements are payouts with an externalRef starting with auto_settle_.
- Alert on drift
If your books disagree, the missing movement is in that list — match it by id.