Developer guide
VEX Pay siteAPI reference
Browse documentation

Marketplace: split one payment between comercios

One buyer payment, up to 10 comercios: each gets its share minus your commission and its part of the VEX Pay fee, and can be paid out automatically.

What you will build

A store that sells products from several comercios in one cart charges the buyer once and sends splits: one share per comercio. When the bank confirms the payment, VEX Pay credits each comercio its share minus your commission and its part of the VEX Pay fee. Whatever the shares do not cover (shipping, your own products, rounding) stays with you as the marketplace remainder.

MoneyGoes toWhen
Share − commission − its part of the VEX Pay feeThe comercio’s balance (pending, then available)Credited when the payment completes; available after bank confirmation and your seller hold
Your commission on each shareYour balanceWhen the bank confirms the payment
The remainder (not in any share), minus its part of the feeYour balanceWhen the bank confirms the payment
VEX Pay feeVEX Pay—

Step 01

Create and verify each comercio

Each comercio is a merchant of your account. Create it with your own comercio id as externalRef, add its Pago Móvil or bank account, and have it confirm the two micro-deposits. Only verified comercios are paid out.

curlbash
curl --request POST "${API_URL}/v1/merchants" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "externalRef": "comercio-17", "name": "Panaderia 17", "identification": "J123456789", "contactEmail": "ventas@panaderia17.com", "contactPhone": "04141873562", "bankCode": "0105", "phone": "04141873562", "autoPayoutEnabled": true }'

Then start and confirm verification exactly as in Recipe: marketplace (/verify/start, then /verify with the two amounts). Set a negotiated commission per comercio with PATCH /v1/merchants/{id} and applicationFeePercent; a share without its own commission uses it.

Step 02

Charge once, with splits

Send splits on débito inmediato (POST /v1/payments/debit), C2P (/v1/payments/c2p/request or /v1/payments/c2p), Pago Móvil verify (/v1/payments/pago-movil/verify) or VPOS (/v1/payments/vpos). Each share has:

FieldRequiredMeaning
merchantIdYesA comercio of your account (UUID or mrc_… id). At most once per payment.
amountYesThe comercio’s share in the request’s currency: "6000.00" (string, two decimals) or a number with at most two decimals. VES for débito, C2P and Pago Móvil; for VPOS, VES when you send vesAmount, else USD (converted at the payment’s rate and rounded down to Bs 0.01).
applicationFeePercentNoYour commission as a percent of the share’s VES amount.
applicationFeeVesNoYour commission in VES (two decimals). Not with applicationFeePercent.
referenceNoUp to 64 characters, returned as sent (for example your order line).
Débito inmediato with two comercios (curl)bash
curl --request POST "${API_URL}/v1/payments/debit" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "banco": "0191",
    "monto": 10000,
    "telefono": "04141873562",
    "cedula": "V12345678",
    "nombre": "Maria Perez",
    "otp": "12345678",
    "concepto": "Pedido 1042",
    "splits": [
      { "merchantId": "MERCHANT_A", "amount": "6000.00", "applicationFeePercent": 20, "reference": "1042/a" },
      { "merchantId": "MERCHANT_B", "amount": "3000.00", "applicationFeePercent": 20, "reference": "1042/b" }
    ]
  }'

VEX Pay checks every share before calling the bank. If one is wrong, the request fails with 400 invalid_data and field: "splits" and no money moves.

When you omit both commission fields on a share, VEX Pay uses the comercio’s negotiated commission, then your default commission, then none.

Step 03

How each comercio’s net is computed

Comercio net = share − commission − share’s part of the VEX Pay fee. With a percent commission, that is share × (1 − VEX Pay rate − commission %), so you can pick each comercio’s applicationFeePercent to reach the net you agreed with it.

Worked example: the buyer pays Bs 10,000. Comercio A has a share of Bs 6,000 and comercio B Bs 3,000, both with a 20% commission. Your VEX Pay fee is 3% and Bs 1,000 (shipping) is in no share.

PartAmountCommission (20%)VEX Pay fee (3%)Net
Comercio ABs 6,000.00Bs 1,200.00Bs 180.00Bs 4,620.00 to comercio A
Comercio BBs 3,000.00Bs 600.00Bs 90.00Bs 2,310.00 to comercio B
Remainder (shipping)Bs 1,000.00—Bs 30.00Bs 970.00 to you
TotalBs 10,000.00Bs 1,800.00 to youBs 300.00You keep Bs 2,770.00
  • The payment’s VEX Pay fee is computed as usual on the whole amount, then shared by each part in proportion to its amount.
  • If a comercio has its own VEX Pay pricing, its share pays that rate instead; your fixed fee per payment (if any) is shared in proportion. The payment’s fee is then the sum.
  • Fees are split to the exact cent: each share gets its proportional part, and the leftover cents go to the largest fractions (the remainder counts as one more part). Shares never add up to more than the payment, and comercios never receive more than the payment’s net.
  • A share whose commission and fee take all of it credits the comercio nothing.

Each read of the payment (GET /v1/payments/{id}, by reference) and every payment.* webhook carries splits[] with amountVes, applicationFeeVes, feeVes and netVes per comercio (fee and net appear once the payment completes). The comercio’s transactions and monthly statement show the credit with the paymentId and the share’s splitReference.

Step 04

Pay comercios automatically

A comercio with autoPayoutEnabled: true is paid its whole available balance to its verified payout account, with the merchant payout fee in your pricing. Once you set a default or a minimum in your marketplace settings, this runs every 15 minutes; until then each comercio is paid at most once a day, as before. It never pays sales still awaiting bank confirmation or within your seller hold, and it never has two automatic payouts in flight at once.

Marketplace settings (curl)bash
curl "${API_URL}/v1/marketplace/settings" --header "x-api-key: ${VEXPAY_API_KEY}"

curl --request PATCH "${API_URL}/v1/marketplace/settings" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "merchantAutoPayoutDefault": true, "merchantAutoPayoutMinUsd": "10.00" }'
SettingEffect
merchantAutoPayoutDefaulttrue: comercios you create without autoPayoutEnabled start with auto-payout on. Existing comercios keep their setting.
merchantAutoPayoutMinUsdNo automatic payout below this amount (USD at the BCV rate); the balance waits for more sales. null = any balance of Bs 1 or more.

A failed automatic payout returns the money to the comercio’s available balance and is retried in the next cycle. After 3 failures in a row, automatic payouts for that comercio stop for 24 hours and VEX Pay ops is alerted. You get payout.completed / payout.failed for each one, as for any payout.

Step 05

Reversals and limits

A full reversal of a split payment takes each comercio’s credit back (from pending, or from available if it was already released) and returns your commission and remainder, so every balance nets to zero for that payment. Partial refunds of a split payment are not supported yet and are refused with a clear error.

RuleWhat happens otherwise
1 to 10 shares, each comercio once400 invalid_data
Every comercio is yours, active and not removed400 invalid_data
Shares add up to at most the payment amount400 invalid_data
Each commission is at most its share400 invalid_data
Not together with merchantId, applicationFeeVes or applicationFeePercent at the top level400 invalid_data
Not together with onwardPayout (USDT forwarding)400 invalid_data
Only on débito inmediato, C2P, Pago Móvil verify and VPOSCheckout sessions, USDT and peso payments refuse splits with a 400 naming the supported methods

For C2P you can send splits on the request (/v1/payments/c2p/request) or on the execute call, not both. Resending the exact same shares on execute (for example after a failed attempt) is accepted. A payment with shares never takes onwardPayout, including on a C2P execute or a Pago Móvil retry with the same reference.