Marketplace: divide un pago entre comercios
Un pago del comprador, hasta 10 comercios: cada uno recibe su parte menos tu comisión y su parte de la comisión de VEX Pay, y se le puede pagar automáticamente.
Lo que vas a construir
Una tienda que vende productos de varios comercios en un mismo carrito cobra al comprador una sola vez y envía splits: una parte por comercio. Cuando el banco confirma el pago, VEX Pay acredita a cada comercio su parte menos tu comisión y su parte de la comisión de VEX Pay. Lo que las partes no cubren (envío, tus propios productos, redondeo) queda contigo como remanente del marketplace.
| Dinero | Va a | Cuándo |
|---|---|---|
| Parte − comisión − su parte de la comisión de VEX Pay | El saldo del comercio (pendiente, luego disponible) | Se acredita cuando el pago se completa; disponible tras la confirmación del banco y tu retención de vendedores |
| Tu comisión sobre cada parte | Tu saldo | Cuando el banco confirma el pago |
| El remanente (fuera de toda parte), menos su parte de la comisión | Tu saldo | Cuando el banco confirma el pago |
| Comisión de VEX Pay | VEX Pay | — |
Paso 01
Crea y verifica cada comercio
Cada comercio es un merchant de tu cuenta. Créalo con tu propio id de comercio como externalRef, agrega su Pago Móvil o cuenta bancaria y pídele que confirme los dos microdepósitos. Solo se les paga a comercios verificados.
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 }'Luego inicia y confirma la verificación igual que en Receta: marketplace (/verify/start, luego /verify con los dos montos). Define una comisión negociada por comercio con PATCH /v1/merchants/{id} y applicationFeePercent; una parte sin comisión propia usa esa.
Paso 02
Cobra una vez, con splits
Envía splits en débito inmediato (POST /v1/payments/debit), C2P (/v1/payments/c2p/request o /v1/payments/c2p), verificación de Pago Móvil (/v1/payments/pago-movil/verify) o VPOS (/v1/payments/vpos). Cada parte tiene:
| Campo | Obligatorio | Significado |
|---|---|---|
| merchantId | Sí | Un comercio de tu cuenta (UUID o id mrc_…). Una vez por pago como máximo. |
| amount | Sí | La parte del comercio en la moneda de la solicitud: "6000.00" (texto, dos decimales) o un número con dos decimales como máximo. VES en débito, C2P y Pago Móvil; en VPOS, VES si envías vesAmount, si no USD (convertido a la tasa del pago y redondeado hacia abajo a Bs 0,01). |
| applicationFeePercent | No | Tu comisión como porcentaje del monto en VES de la parte. |
| applicationFeeVes | No | Tu comisión en VES (dos decimales). No junto con applicationFeePercent. |
| reference | No | Hasta 64 caracteres, se devuelve tal cual (por ejemplo, tu línea de pedido). |
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 revisa cada parte antes de llamar al banco. Si una está mal, la solicitud falla con 400 invalid_data y field: "splits", y no se mueve dinero.
Si omites ambos campos de comisión en una parte, VEX Pay usa la comisión negociada del comercio, luego tu comisión por defecto, luego ninguna.
Paso 03
Cómo se calcula el neto de cada comercio
Neto del comercio = parte − comisión − parte de la comisión de VEX Pay. Con una comisión en porcentaje, es parte × (1 − tasa de VEX Pay − % de comisión), así que puedes elegir el applicationFeePercent de cada comercio para llegar al neto que acordaste con él.
Ejemplo: el comprador paga Bs 10.000. El comercio A tiene una parte de Bs 6.000 y el comercio B de Bs 3.000, ambos con 20% de comisión. Tu comisión de VEX Pay es 3% y Bs 1.000 (envío) no están en ninguna parte.
| Parte | Monto | Comisión (20%) | Comisión VEX Pay (3%) | Neto |
|---|---|---|---|---|
| Comercio A | Bs 6.000,00 | Bs 1.200,00 | Bs 180,00 | Bs 4.620,00 al comercio A |
| Comercio B | Bs 3.000,00 | Bs 600,00 | Bs 90,00 | Bs 2.310,00 al comercio B |
| Remanente (envío) | Bs 1.000,00 | — | Bs 30,00 | Bs 970,00 para ti |
| Total | Bs 10.000,00 | Bs 1.800,00 para ti | Bs 300,00 | Te quedan Bs 2.770,00 |
- La comisión de VEX Pay del pago se calcula como siempre sobre el monto total y luego se reparte entre las partes en proporción a su monto.
- Si un comercio tiene su propio precio de VEX Pay, su parte paga esa tasa; tu cargo fijo por pago (si lo hay) se reparte en proporción. La comisión del pago es entonces la suma.
- Las comisiones se reparten al céntimo exacto: cada parte recibe su proporción y los céntimos sobrantes van a las fracciones más grandes (el remanente cuenta como una parte más). Las partes nunca suman más que el pago, y los comercios nunca reciben más que el neto del pago.
- Una parte cuya comisión y cargo se la llevan completa no le acredita nada al comercio.
Cada lectura del pago (GET /v1/payments/{id}, por referencia) y cada webhook payment.* trae splits[] con amountVes, applicationFeeVes, feeVes y netVes por comercio (cargo y neto aparecen cuando el pago se completa). Los movimientos y el estado de cuenta mensual del comercio muestran el crédito con el paymentId y el splitReference de la parte.
Paso 04
Paga a los comercios automáticamente
A un comercio con autoPayoutEnabled: true se le paga todo su saldo disponible a su cuenta de pago verificada, con la comisión de payout a comercios de tu precio. Cuando defines un valor por defecto o un mínimo en la configuración del marketplace, esto corre cada 15 minutos; mientras tanto, a cada comercio se le paga como máximo una vez al día, como antes. Nunca paga ventas que esperan confirmación del banco o que siguen en tu retención de vendedores, y nunca tiene dos payouts automáticos en curso a la vez.
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" }'| Ajuste | Efecto |
|---|---|
| merchantAutoPayoutDefault | true: los comercios que crees sin autoPayoutEnabled empiezan con payout automático. Los comercios existentes conservan su ajuste. |
| merchantAutoPayoutMinUsd | No hay payout automático por debajo de este monto (USD a tasa BCV); el saldo espera más ventas. null = cualquier saldo desde Bs 1. |
Un payout automático fallido devuelve el dinero al saldo disponible del comercio y se reintenta en el siguiente ciclo. Tras 3 fallas seguidas, los payouts automáticos de ese comercio se detienen 24 horas y se alerta al equipo de operaciones de VEX Pay. Recibes payout.completed / payout.failed por cada uno, como en cualquier payout.
Paso 05
Reversos y límites
Un reverso total de un pago dividido retira el crédito de cada comercio (del pendiente, o del disponible si ya se liberó) y devuelve tu comisión y remanente, así que cada saldo queda en cero para ese pago. Los reembolsos parciales de un pago dividido aún no están disponibles y se rechazan con un error claro.
| Regla | Si no se cumple |
|---|---|
| De 1 a 10 partes, cada comercio una vez | 400 invalid_data |
| Cada comercio es tuyo, está activo y no fue eliminado | 400 invalid_data |
| Las partes suman como máximo el monto del pago | 400 invalid_data |
| Cada comisión es como máximo su parte | 400 invalid_data |
| No junto con merchantId, applicationFeeVes o applicationFeePercent en el nivel superior | 400 invalid_data |
| No junto con onwardPayout (reenvío a USDT) | 400 invalid_data |
| Solo en débito inmediato, C2P, verificación de Pago Móvil y VPOS | Las sesiones de checkout, USDT y pagos en pesos rechazan splits con un 400 que nombra los métodos admitidos |
En C2P puedes enviar splits en la solicitud (/v1/payments/c2p/request) o en la ejecución, no en ambas. Reenviar exactamente las mismas partes en la ejecución (por ejemplo, tras un intento fallido) se acepta. Un pago con partes nunca acepta onwardPayout, tampoco en la ejecución de C2P ni al reintentar un Pago Móvil con la misma referencia.