Balances, holds and payouts

What is available, what is held and why, how the 24h hold works in every currency, 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
Held	Credited in the last 24 hours (the balance hold)	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

Bolívaresbash

curl "${API_URL}/v1/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
# availableVes = ledgerNetVes − reserveVes − heldVes

USDT / USDCbash

curl "${API_URL}/v1/crypto/balances" --header "x-api-key: ${VEXPAY_API_KEY}"
# each: available, held, nextReleaseAt, pendingPayout (USDT also availableUsdt, heldUsdt)

Pesosbash

curl "${API_URL}/v1/cop/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
# availableCop, heldCop, nextReleaseAt, pendingPayoutCop

Every credit to your balance is held for balanceHoldHours (24 for live accounts, 0 in test mode) from the moment it is credited. Nothing needs to happen to release it: at nextReleaseAt it simply becomes available.

Movement	Held for 24h?
Completed payments (every method and currency), net of the VEXPay fee	Yes
USDT credited by a conversion	Only the part bought with money that was still held — until that original hold ends
Won chargebacks and positive adjustments	Yes
Money coming back: failed payouts, canceled conversions, fee reversals	No — it returns exactly as it left

While money is held, you can…	Rule
Pay out (bank, seller, crypto wallet)	No — payouts spend available money only
Convert to USDT	Yes — the USDT stays held until the original hold ends
Transfer to a seller	Yes — the seller cannot be paid before the hold ends
Be refunded, reversed or charged back	Yes — these come out of the held amount first

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:

422 insufficient_balancejson

{
  "error": "insufficient_balance",
  "availableVes": "3000.00",
  "requestedVes": "4000.00",
  "heldVes": "4342.50",
  "nextReleaseAt": "2026-10-20T00:48:52.784Z"
}

Pay out at most the available amount now, or schedule the rest for after nextReleaseAt.
Do not retry in a loop — nothing changes until a hold ends or new money arrives.
USDT payouts answer the same way with availableUsdt, heldUsdt and nextReleaseAt; ops COP payouts with availableCop and heldCop.

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 fee + 0.25 USDT (e.g. 1.00 USDT on BEP20, Polygon and Solana)
USDC to an external wallet	0.75 USDC on BASE and Polygon (0.50 network fee + 0.25)
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 the hold
Movements still held carry availableAt. Sum minus reserveVes minus heldVes equals availableVes.
Alert on drift
If your books disagree, the missing movement is in that list — match it by id.

The parts of a balance

How the 24h hold works

When a payout is refused

What payouts cost

Reconcile it