Recipe: run a marketplace with sellers

Collect from buyers, keep your commission automatically, and pay each seller from their own balance once their sale is released.

What you will build

A marketplace where every sale is tagged with its seller. VEXPay keeps your commission, credits the seller’s net to their own balance, and lets you pay them out to their verified Pago Móvil — with no split math in your code.

Money	Goes to	When it can be paid out
Your commission (applicationFeePercent)	Your balance	24h after the sale (tenant hold)
Seller net	The seller’s pending balance	After the later of your seller hold and 24h
VEXPay fee	VEXPay	—

Step 01

Onboard and verify each seller

curlbash

# 1. Create the seller (externalRef = your seller id)
curl --request POST "${API_URL}/v1/merchants" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "externalRef": "seller_47", "name": "Maria Perez", "identification": "V12345678", "contactEmail": "maria@mail.com", "contactPhone": "04141234567" }'

# 2. Add their Pago Móvil destination
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. Send two micro-deposits, then confirm the amounts the seller sees
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" }'

Listen for merchant.verified (or merchant.rejected with the bank’s reason). Look sellers up later with GET /v1/merchants?externalRef=seller_47.

Step 02

Charge the buyer for the seller

Add merchantId and your commission to the charge. When it completes, VEXPay keeps the commission in your balance and moves the seller’s net into their pending balance.

C2P with a seller (curl)bash

curl --request POST "${API_URL}/v1/payments/c2p" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "intentId": "INTENT_ID",
    "usdAmount": 40.00,
    "debtorId": "V87654321",
    "debtorCellPhone": "584121234567",
    "debtorBankCode": 102,
    "token": "123456",
    "externalRef": "order-77",
    "merchantId": "MERCHANT_ID",
    "applicationFeePercent": 10
  }'

Step 03

Pay the seller from their balance

Watch the seller balance
GET /v1/merchants/:id/balance returns pendingVes and availableVes. merchant.balance.updated fires when a sale lands or is released.
Wait for the release
A seller sale is released after the later of your seller hold (sellerHoldBusinessDays) and the 24h balance hold — never earlier, even if your seller hold is 0. This applies to bolívar, USDT and peso sales.
Pay out
POST /v1/payouts with merchantId, the amount and fromMerchantBalance: true. The payout debits the seller’s available balance, not yours.

curlbash

curl --request POST "${API_URL}/v1/payouts" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "merchantId": "MERCHANT_ID", "monto": "1200.00", "concepto": "Ventas semana 42", "externalRef": "po_seller_47_w42", "fromMerchantBalance": true }'

A refund or reversal during the hold is taken back from the seller’s pending balance automatically. Your platform totals — your own available funds and what you owe sellers — are on GET /v1/balance (platformAvailableVes, sellerPendingVes, sellerAvailableVes).