Receta: opera un marketplace con vendedores

Cobra a los compradores, retén tu comisión automáticamente y paga a cada vendedor desde su propio saldo cuando su venta se libere.

Lo que vas a construir

Un marketplace donde cada venta lleva la marca de su vendedor. VEXPay retiene tu comisión, acredita el neto del vendedor en su propio saldo y te permite pagarle a su Pago Móvil verificado, sin cálculos de reparto en tu código.

Dinero	Va a	Cuándo se puede pagar
Tu comisión (applicationFeePercent)	Tu saldo	Cuando el banco confirma la venta
Neto del vendedor	El saldo pendiente del vendedor	Cuando termina tu retención de vendedores
Comisión de VEXPay	VEXPay	—

Paso 01

Registra y verifica a cada vendedor

curlbash

# 1. Crea el vendedor (externalRef = tu id de vendedor)
curl --request POST "${API_URL}/v1/merchants" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "externalRef": "seller_47", "name": "Maria Perez", "identification": "V12345678", "contactEmail": "maria@mail.com", "contactPhone": "04141234567" }'

# 2. Agrega su destino Pago Móvil
curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "bankCode": "0105", "phone": "04141234567" }'

# 3. Envía dos microdepósitos y luego confirma los montos que ve el vendedor
curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods/METHOD_ID/verify/start" --header "x-api-key: ${VEXPAY_API_KEY}"
curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods/METHOD_ID/verify" \
  --header "content-type: application/json" --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "amount1": "0.37", "amount2": "0.82" }'

Escucha merchant.verified (o merchant.rejected con el motivo del banco). Más adelante, busca vendedores con GET /v1/merchants?externalRef=seller_47.

Paso 02

Cobra al comprador en nombre del vendedor

Agrega merchantId y tu comisión al cobro. Cuando se completa, VEXPay deja la comisión en tu saldo y mueve el neto del vendedor a su saldo pendiente.

C2P con un vendedor (curl)bash

curl --request POST "${API_URL}/v1/payments/c2p" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "intentId": "INTENT_ID",
    "usdAmount": 40.00,
    "debtorId": "V87654321",
    "debtorCellPhone": "584121234567",
    "debtorBankCode": 102,
    "token": "123456",
    "externalRef": "order-77",
    "merchantId": "MERCHANT_ID",
    "applicationFeePercent": 10
  }'

¿Prefieres un link? Crea una sesión de checkout con merchantId y el comprador paga en la página alojada; el reparto es el mismo. Las sesiones con vendedor ofrecen solo métodos en bolívares (c2p, pago_movil, vpos) y muestran el nombre público del vendedor en el checkout. Esta acepta solo Pago Móvil y te deja el 3%; el 97% del vendedor, menos la comisión de VEXPay, llega a su saldo pendiente.

Link de Pago Móvil con un vendedor (curl)bash

curl --request POST "${API_URL}/v1/checkout/sessions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountUsd": 20.00,
    "methods": ["pago_movil"],
    "merchantId": "MERCHANT_ID",
    "applicationFeePercent": 3,
    "reference": "class-1042"
  }'

Paso 03

Paga al vendedor desde su saldo

Vigila el saldo del vendedor
GET /v1/merchants/:id/balance devuelve pendingVes y availableVes. merchant.balance.updated se dispara cuando una venta llega o se libera.
Espera la liberación
Una venta del vendedor se libera cuando termina tu retención de vendedores (sellerHoldBusinessDays). Esto aplica a ventas en bolívares, USDT y pesos.
Envía el payout
POST /v1/payouts con merchantId, el monto y fromMerchantBalance: true. El payout descuenta del saldo disponible del vendedor, no del tuyo.

curlbash

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": "Ventas semana 42", "externalRef": "po_seller_47_w42", "fromMerchantBalance": true }'

Un reembolso o reverso durante la retención se descuenta automáticamente del saldo pendiente del vendedor. Los totales de tu plataforma (tus propios fondos disponibles y lo que debes a los vendedores) están en GET /v1/balance (platformAvailableVes, sellerPendingVes, sellerAvailableVes).