Split a payment between your marketplace and a seller

Create a checkout session with `merchantId` and `applicationFeePercent`: you keep your commission, the seller's share lands in their balance, and you pay them out once it is released.

What you will do

Tag a checkout with a seller and VEXPay splits it when it is paid: your commission stays in your balance and the seller's share goes to the seller's own balance, ready to pay out after the hold.

A marketplace account with bolívar methods enabled (split checkouts take card, Débito Inmediato and Pago Móvil only).
An active seller with a verified payout method (see Onboard a seller).

Steps

Create a split checkout session
POST /v1/checkout/sessions with amountUsd, merchantId (the seller) and optionally applicationFeePercent (0–100, up to 4 decimals). Without it, VEXPay uses the seller's commission, then your default commission, then none.
Send the buyer the url
The checkout shows the seller's name, because the buyer is paying the seller.
VEXPay splits on completion
When the payment completes, your commission stays in your balance and the seller net goes to the seller's pending balance. You receive payment.completed and merchant.balance.updated.
Wait for the release
The seller's pending money becomes available after the later of the seller hold and your 24-hour balance hold.
Pay the seller
POST /v1/payouts with merchantId, the exact bolívar monto, concepto, a unique externalRef and fromMerchantBalance: true. Or turn on autoPayoutEnabled for the seller.

Split checkoutbash

curl --request POST "${API_URL}/v1/checkout/sessions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountUsd": 40.00,
    "description": "Order #7781",
    "reference": "order-7781",
    "merchantId": "MERCHANT_ID",
    "applicationFeePercent": 5
  }'

Pay the sellerbash

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": "Sales week 44",
    "externalRef": "seller-881-w44",
    "fromMerchantBalance": true
  }'

Check that it worked

GET /v1/checkout/sessions/:id shows status: "paid" and echoes merchantId and applicationFeePercent.
GET /v1/merchants/:id/balance shows the seller net in pendingVes, later in availableVes.
After the payout, payout.completed arrives and the seller's available balance goes down by monto.

If something goes wrong

Symptom	Likely cause	What to do
400 on a session with `usdt`, `usdc` or `cop` and `merchantId`	Split checkouts take bolívar methods only	Drop those methods, or remove `merchantId`.
400 "merchantId is required when setting an application fee"	Commission sent without a seller	Add `merchantId`.
400 `merchantId not found or inactive for this tenant`	Wrong id, another account's seller, or a deactivated seller	Check `GET /v1/merchants/:id`; reactivate with `PATCH /v1/merchants/:id`.
Seller balance not credited	No `merchantId` on the payment, or fee + commission ≥ amount	Check the payment; lower the commission.
422 `insufficient_merchant_balance` on payout	Seller money still pending, or already paid out	Wait for the release; check `GET /v1/merchants/:id/balance`.
Payout status `awaiting_approval`	In its first 30 days an account can pay out up to USD 300 in any rolling 24 hours (unless VEXPay set a different limit for you); this payout went over it	No action needed; VEXPay reviews it and sends it or returns the funds.