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.
| Money | Goes to | When |
|---|---|---|
| Share − commission − its part of the VEX Pay fee | The comercio’s balance (pending, then available) | Credited when the payment completes; available after bank confirmation and your seller hold |
| Your commission on each share | Your balance | When the bank confirms the payment |
| The remainder (not in any share), minus its part of the fee | Your balance | When the bank confirms the payment |
| VEX Pay fee | VEX 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.
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:
| Field | Required | Meaning |
|---|---|---|
| merchantId | Yes | A comercio of your account (UUID or mrc_… id). At most once per payment. |
| amount | Yes | The 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). |
| applicationFeePercent | No | Your commission as a percent of the share’s VES amount. |
| applicationFeeVes | No | Your commission in VES (two decimals). Not with applicationFeePercent. |
| reference | No | Up to 64 characters, returned as sent (for example your order line). |
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.
| Part | Amount | Commission (20%) | VEX Pay fee (3%) | Net |
|---|---|---|---|---|
| Comercio A | Bs 6,000.00 | Bs 1,200.00 | Bs 180.00 | Bs 4,620.00 to comercio A |
| Comercio B | Bs 3,000.00 | Bs 600.00 | Bs 90.00 | Bs 2,310.00 to comercio B |
| Remainder (shipping) | Bs 1,000.00 | — | Bs 30.00 | Bs 970.00 to you |
| Total | Bs 10,000.00 | Bs 1,800.00 to you | Bs 300.00 | You 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.
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" }'| Setting | Effect |
|---|---|
| merchantAutoPayoutDefault | true: comercios you create without autoPayoutEnabled start with auto-payout on. Existing comercios keep their setting. |
| merchantAutoPayoutMinUsd | No 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.
| Rule | What happens otherwise |
|---|---|
| 1 to 10 shares, each comercio once | 400 invalid_data |
| Every comercio is yours, active and not removed | 400 invalid_data |
| Shares add up to at most the payment amount | 400 invalid_data |
| Each commission is at most its share | 400 invalid_data |
| Not together with merchantId, applicationFeeVes or applicationFeePercent at the top level | 400 invalid_data |
| Not together with onwardPayout (USDT forwarding) | 400 invalid_data |
| Only on débito inmediato, C2P, Pago Móvil verify and VPOS | Checkout 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.