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	When the bank confirms the sale
Seller net	The seller’s pending balance	After your seller hold
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
  }'

Prefer a link? Create a checkout session with merchantId and the buyer pays on the hosted page — the split is the same. Sessions with a seller offer bolívar methods only (c2p, pago_movil, vpos) and show the seller’s public name on the checkout. This one accepts only Pago Móvil and keeps 3% for you; the seller’s 97%, minus the VEXPay fee, lands in their pending balance.

Pago Móvil link with a seller (curl)bash

curl --request POST "${API_URL}/v1/checkout/sessions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountUsd": 20.00,
    "methods": ["pago_movil"],
    "merchantId": "MERCHANT_ID",
    "applicationFeePercent": 3,
    "reference": "class-1042"
  }'

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 your seller hold (sellerHoldBusinessDays). 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).