Guía para desarrolladores
Sitio de VEX PayReferencia de API
Explorar documentación

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.

DineroVa aCuándo
Parte − comisión − su parte de la comisión de VEX PayEl 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 parteTu saldoCuando el banco confirma el pago
El remanente (fuera de toda parte), menos su parte de la comisiónTu saldoCuando el banco confirma el pago
Comisión de VEX PayVEX 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.

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 }'

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:

CampoObligatorioSignificado
merchantIdSíUn comercio de tu cuenta (UUID o id mrc_…). Una vez por pago como máximo.
amountSí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).
applicationFeePercentNoTu comisión como porcentaje del monto en VES de la parte.
applicationFeeVesNoTu comisión en VES (dos decimales). No junto con applicationFeePercent.
referenceNoHasta 64 caracteres, se devuelve tal cual (por ejemplo, tu línea de pedido).
Débito inmediato con dos 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 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.

ParteMontoComisión (20%)Comisión VEX Pay (3%)Neto
Comercio ABs 6.000,00Bs 1.200,00Bs 180,00Bs 4.620,00 al comercio A
Comercio BBs 3.000,00Bs 600,00Bs 90,00Bs 2.310,00 al comercio B
Remanente (envío)Bs 1.000,00—Bs 30,00Bs 970,00 para ti
TotalBs 10.000,00Bs 1.800,00 para tiBs 300,00Te 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.

Configuración del marketplace (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" }'
AjusteEfecto
merchantAutoPayoutDefaulttrue: los comercios que crees sin autoPayoutEnabled empiezan con payout automático. Los comercios existentes conservan su ajuste.
merchantAutoPayoutMinUsdNo 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.

ReglaSi no se cumple
De 1 a 10 partes, cada comercio una vez400 invalid_data
Cada comercio es tuyo, está activo y no fue eliminado400 invalid_data
Las partes suman como máximo el monto del pago400 invalid_data
Cada comisión es como máximo su parte400 invalid_data
No junto con merchantId, applicationFeeVes o applicationFeePercent en el nivel superior400 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 VPOSLas 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.