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	24 h después de la venta (retención del tenant)
Neto del vendedor	El saldo pendiente del vendedor	Cuando termina la más tardía entre tu retención de vendedores y las 24 h
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
  }'

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 la más tardía entre tu retención de vendedores (sellerHoldBusinessDays) y la retención de 24 h del saldo, nunca antes, aunque tu retención de vendedores sea 0. 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).