Recipe: pay your end users from your sales (disbursements)

What you will build

Your business sells through VEXPay payment links, checkout sessions or charges, and the money lands in your balance. Every pay period (weekly, biweekly, monthly) your admin system credits each end user a dollar amount; VEXPay converts it at the official BCV rate and keeps it in that person's own balance. When a person wants their money, they press Withdraw in your app, your server asks VEXPay for the payout, and the bolívares arrive on their Pago Móvil. Your end users never sign in to VEXPay.

How the pieces fit

• Keep your API key on your server only, never in a mobile app or browser.
• Store the VEXPay merchantId next to each person in your database; use your own id as externalRef.
• In the API an end user is a merchant: the same object marketplaces use for their sellers.

Step 01

Collect your sales

Sell as you do today: portal payment links, checkout sessions or API charges. Each completed sale adds its net (after the VEXPay processing fee) to your balance. Live sales are held for 24 hours (heldVes) before they are available; your balance and every movement are at GET /v1/balance and GET /v1/balance/transactions.

Step 02

Register each end user and verify their Pago Móvil

# 1. Create the end user (externalRef = your own id for the person)
curl --request POST "${API_URL}/v1/merchants" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "externalRef": "emp-104", "name": "Ana Rodriguez", "identification": "V12345678", "contactEmail": "ana@mail.com", "contactPhone": "04141234567" }'

# 2. Add their Pago Móvil
curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "bankCode": "0105", "phone": "04141234567" }'

# 3. Two micro-deposits, then confirm the amounts the person received
curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods/METHOD_ID/verify/start" --header "x-api-key: ${VEXPAY_API_KEY}"
curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods/METHOD_ID/verify" \
  --header "content-type: application/json" --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "amount1": "0.37", "amount2": "0.82" }'

Ask the person, inside your app, for the two small amounts they received. Money only ever leaves to a verified method. Full detail: Onboard a seller.

Step 03

Run the pay period: credit each person in dollars

For each person, send the dollar amount and a transferKey that is unique per person and pay period. VEXPay converts at the BCV rate of that moment, debits your balance and credits the person. If your job crashes and runs again, the same transferKey returns the first result: nobody is paid twice and nobody is re-priced.

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" }'

# 200 →
# { "pendingVes": "0.00", "availableVes": "21540.00", ...,
#   "transfer": { "transferKey": "2026-11-q1-emp-104", "amountVes": "21540.00",
#                 "amountUsd": "100.00", "rate": "215.4000", "rateSource": "bcv",
#                 "rateAsOf": "2026-11-15T13:00:00.000Z" } }

const period = '2026-11-q1';
for (const person of await db.people.activeWithVexpayId()) {
  const res = await fetch(`${process.env.VEXPAY_API_URL}/v1/merchants/${person.vexpayMerchantId}/transfers`, {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'x-api-key': process.env.VEXPAY_API_KEY },
    body: JSON.stringify({ amountUsd: person.amountUsd, transferKey: `${period}-${person.id}` }),
  });
  if (res.status === 503) throw new Error('BCV rate unavailable, retry the run later'); // safe to rerun
  if (!res.ok) { await db.payRun.fail(person.id, await res.json()); continue; }
  const { transfer } = await res.json();
  await db.payRun.record(person.id, transfer); // keep amountVes + rate for your books
}

• Prefer to set bolívares yourself? Send amountVes instead of amountUsd (one or the other).
• Your balance must cover the run: check GET /v1/balance first. A credit you cannot cover answers 422 insufficient_balance and records nothing.
• Credits paid with sales still in their 24-hour hold wait in the person's pendingVes until that hold ends. Running the job the day after the sales came in avoids the wait.

Step 04

Let each person withdraw from your app

Show the person their availableVes (from GET /v1/merchants/:id/balance). When they ask for a withdrawal, your server sends the payout. They receive exactly monto; the withdrawal fee is charged to your balance.

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-0007", "fromMerchantBalance": true }'

# GET /v1/payouts/:id →
# { "status": "completed", "monto": "20000.00", "feeVes": "253.85", "feePayer": "tenant", ... }

• Use a new externalRef per withdrawal request and reuse it on retries: a retry never pays twice.
• Keep a small reserve in your own balance for fees. Without it the withdrawal is refused with 422 insufficient_balance and reason: "tenant_fee_unfunded".
• Listen for payout.completed and payout.failed. If the bank rejects a withdrawal, the money goes back to the person's available balance and the fee back to yours.
• Optionally let people decide how much to withdraw, or withdraw their whole availableVes with one tap.

Step 05

Monthly statements and your own export

Each person's statement shows the opening balance, every credit (with the dollar amount and BCV rate), release and withdrawal in the month, and the closing balance. Months follow Venezuela time. Opening plus the movements always equals closing.

# JSON, for your own screens
curl "${API_URL}/v1/merchants/MERCHANT_ID/statement?month=2026-11" --header "x-api-key: ${VEXPAY_API_KEY}"

# CSV, to send to the person or your accountant
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

# Full history, newest first, paged
curl "${API_URL}/v1/merchants/MERCHANT_ID/transactions?limit=50" --header "x-api-key: ${VEXPAY_API_KEY}"

No code needed for the monthly close: Portal → Merchants → Monthly statement downloads one person, or every person in one CSV with their name and ID on each row. Your own side (sales, credits, fees) is in GET /v1/balance/transactions: credits show as seller_transfer and fees as disbursement_payout_fee.

Go-live checklist

• Run the whole flow with your Test key: a sale, a dollar credit, a withdrawal, a statement (Test everything first).
• Tell VEXPay your number of people and the usual amount per pay period, so the payout limit for new accounts (USD 300 per rolling 24 hours in the first 30 days) is set to fit your payroll. Over it, withdrawals wait in awaiting_approval for review.
• Agree your withdrawal fee price with VEXPay.
• Register a webhook endpoint and handle payout.completed / payout.failed (Set up webhooks).
• Make your pay-period job safe to rerun (same transferKey) and your withdrawals safe to retry (same externalRef).

Questions

Related: Pay your end users · Onboard a seller · Merchants & payouts · Read balance & holds