Disbursements: pay your end users from your sales

Credit each of your end users (staff, contractors, affiliates) in dollars at the BCV rate out of the money you collect, let them withdraw to their own Pago Móvil, and download a monthly statement per person.

What you will do

Your sales land in your VEXPay balance. Each pay period you credit every end user an amount in dollars; VEXPay converts it at the official BCV rate and keeps it in that person's balance. Each person then withdraws to their own Pago Móvil when they want, through your own system. You pay the withdrawal fee, not them. Each end user is a merchant in the API.

Disbursements turned on for your account. Ask VEXPay; it works in Test mode right away and in Live after go-live approval.
Your server holds your API key. Your end users never sign in to VEXPay: your admin system calls the API for them.
Each end user registered with a verified Pago Móvil (see Onboard a seller).

Steps

Collect
Sell with payment links, checkout sessions or charges as usual. Each sale is held for 24 hours in your balance (heldVes) before it is available.
Register your end users
POST /v1/merchants once per person, then add and verify their Pago Móvil payout method. Keep the returned merchantId in your system next to the person.
Credit each person in dollars
POST /v1/merchants/:id/transfers with amountUsd and a transferKey that is unique per person and pay period (for example 2026-11-q1-emp-104). The response shows amountVes, the rate and rateAsOf. Sending the same transferKey again returns the first result, never a second credit at a new rate.
The person withdraws
When the person asks for a withdrawal in your system, call POST /v1/payouts with their merchantId, the bolívar monto, concepto, a unique externalRef and fromMerchantBalance: true. They receive the full monto; the withdrawal fee is charged to your balance.
Download the month
GET /v1/merchants/:id/statement?month=2026-11 (add &format=csv for a file), or Portal → Merchants → Monthly statement for one person or everyone in one CSV.

Credit $100 at BCVbash

curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/transfers" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountUsd": "100.00",
    "transferKey": "2026-11-q1-emp-104"
  }'
# → { "pendingVes": "...", "availableVes": "...",
#     "transfer": { "amountVes": "21540.00", "amountUsd": "100.00", "rate": "215.4000", "rateSource": "bcv", ... } }

Withdrawalbash

curl --request POST "${API_URL}/v1/payouts" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "merchantId": "MERCHANT_ID",
    "monto": "20000.00",
    "concepto": "Retiro",
    "externalRef": "wd-emp-104-0001",
    "fromMerchantBalance": true
  }'

Monthly statement (CSV)bash

curl "${API_URL}/v1/merchants/MERCHANT_ID/statement?month=2026-11&format=csv" \
  --header "x-api-key: ${VEXPAY_API_KEY}" --output emp-104-2026-11.csv

When the money can be withdrawn

A credit paid with money that is already available in your balance can be withdrawn at once. A credit paid with sales still in their 24-hour hold sits in the person's pendingVes and moves to availableVes when that hold ends. Crediting the day after the sales came in avoids the wait.

The withdrawal fee

Each withdrawal costs a percentage of monto with a minimum in dollars, plus a fixed part in dollars; the dollar parts convert at the BCV rate of that moment. VEXPay agrees the price with you before you go live.

Example: 1% (min $0.25) + $0.25, BCV 215.40	Fee
Withdrawal of Bs 20,000.00	Bs 200.00 + Bs 53.85 = Bs 253.85
Withdrawal of Bs 2,000.00	Bs 53.85 (minimum) + Bs 53.85 = Bs 107.70

The payout shows feeVes and feePayer: "tenant"; the person was debited only monto.
Your balance shows a disbursement_payout_fee movement. If the bank rejects the withdrawal, monto goes back to the person and the fee back to you (disbursement_payout_fee_reversal).
Keep a small reserve in your balance: if it cannot cover the fee, the withdrawal is refused with 422 insufficient_balance and reason: "tenant_fee_unfunded".

Check that it worked

GET /v1/merchants/:id/balance shows the credit in pendingVes or availableVes.
GET /v1/merchants/:id/transactions lists credits (with amountUsd and rate), releases and withdrawals, newest first.
In the statement, opening + the sum of amountVes = closing. A release row moves money from pending to available, so its amountVes is 0.00.

Leftovers and chargebacks

Money you credit belongs to the person until they withdraw it; VEXPay does not take it back on its own. Credit only what you owe.
Months are in Venezuela time (America/Caracas).
A refund or card chargeback on one of your sales is taken from your balance, even if you already credited that money to your end users. Recovering it from them is up to you.

If something goes wrong

Symptom	Likely cause	What to do
422 `insufficient_balance` on a credit	Your balance cannot cover it	Check `GET /v1/balance`; wait for more sales.
503 `rate_unavailable` on a credit or withdrawal	The BCV rate could not be read just now; nothing was recorded	Retry in a minute with the same `transferKey` or `externalRef`.
422 `insufficient_merchant_balance` on a withdrawal	The credit is still pending (sales in hold), or the person has less available	Check `GET /v1/merchants/:id/balance`; wait for the release.
422 `insufficient_balance` with `reason: "tenant_fee_unfunded"`	Your balance cannot pay the withdrawal fee	Keep a reserve; retry with the same `externalRef`.
Withdrawal `awaiting_approval`	Over the first-30-days payout limit	No action; VEXPay reviews it.