Dispersión de pagos: paga a tus usuarios con tus ventas

Qué vas a hacer

Tus ventas llegan a tu saldo de VEXPay. En cada período acreditas a cada usuario final un monto en dólares; VEXPay lo convierte a la tasa oficial BCV y lo guarda en el saldo de esa persona. Luego cada persona retira a su propio Pago Móvil cuando quiera, desde tu propio sistema. La comisión de retiro la pagas tú, no ellos. En la API, cada usuario final es un merchant.

• La dispersión de pagos activada en tu cuenta. Pídela a VEXPay; funciona en modo Test de inmediato y en Live después de la aprobación de salida a producción.
• Tu servidor guarda tu API key. Tus usuarios finales nunca entran a VEXPay: tu sistema administrativo llama a la API por ellos.
• Cada usuario final registrado con un Pago Móvil verificado (mira Registrar un vendedor).

Pasos

1. 01
   Cobra

   Vende con links de pago, sesiones de checkout o cobros como siempre. Cada venta queda retenida 24 horas en tu saldo (heldVes) antes de estar disponible.

2. 02
   Registra a tus usuarios finales

   POST /v1/merchants una vez por persona; luego agrega y verifica su método de payout Pago Móvil. Guarda el merchantId que recibes en tu sistema, junto a la persona.

3. 03
   Acredita a cada persona en dólares

   POST /v1/merchants/:id/transfers con amountUsd y un transferKey único por persona y período (por ejemplo 2026-11-q1-emp-104). La respuesta muestra amountVes, la tasa (rate) y rateAsOf. Si envías el mismo transferKey otra vez recibes el primer resultado, nunca un segundo crédito a otra tasa.

4. 04
   La persona retira

   Cuando la persona pide un retiro en tu sistema, llama a POST /v1/payouts con su merchantId, el monto en bolívares, concepto, un externalRef único y fromMerchantBalance: true. Recibe el monto completo; la comisión de retiro se cobra de tu saldo.

5. 05
   Descarga el mes

   GET /v1/merchants/:id/statement?month=2026-11 (agrega &format=csv para un archivo), o Portal → Merchants → Monthly statement para una persona o para todas en un solo CSV.

curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/transfers" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountUsd": "100.00",
    "transferKey": "2026-11-q1-emp-104"
  }'
# → { "pendingVes": "...", "availableVes": "...",
#     "transfer": { "amountVes": "21540.00", "amountUsd": "100.00", "rate": "215.4000", "rateSource": "bcv", ... } }

curl --request POST "${API_URL}/v1/payouts" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "merchantId": "MERCHANT_ID",
    "monto": "20000.00",
    "concepto": "Retiro",
    "externalRef": "wd-emp-104-0001",
    "fromMerchantBalance": true
  }'

curl "${API_URL}/v1/merchants/MERCHANT_ID/statement?month=2026-11&format=csv" \
  --header "x-api-key: ${VEXPAY_API_KEY}" --output emp-104-2026-11.csv

Cuándo se puede retirar el dinero

Un crédito pagado con dinero que ya está disponible en tu saldo se puede retirar de inmediato. Un crédito pagado con ventas que siguen en su retención de 24 horas queda en el pendingVes de la persona y pasa a availableVes cuando esa retención termina. Acreditar al día siguiente de las ventas evita la espera.

La comisión de retiro

Cada retiro cuesta un porcentaje del monto con un mínimo en dólares, más una parte fija en dólares; las partes en dólares se convierten a la tasa BCV de ese momento. VEXPay acuerda el precio contigo antes de salir a producción.

• El payout muestra feeVes y feePayer: "tenant"; a la persona solo se le debitó el monto.
• Tu saldo muestra un movimiento disbursement_payout_fee. Si el banco rechaza el retiro, el monto vuelve a la persona y la comisión vuelve a ti (disbursement_payout_fee_reversal).
• Mantén una pequeña reserva en tu saldo: si no alcanza para la comisión, el retiro se rechaza con 422 insufficient_balance y reason: "tenant_fee_unfunded".

Comprueba que funcionó

• GET /v1/merchants/:id/balance muestra el crédito en pendingVes o availableVes.
• GET /v1/merchants/:id/transactions lista créditos (con amountUsd y rate), liberaciones y retiros, del más reciente al más antiguo.
• En el estado de cuenta, saldo inicial + la suma de amountVes = saldo final. Una fila release mueve dinero de pendiente a disponible, por eso su amountVes es 0.00.

Sobrantes y contracargos

• El dinero que acreditas es de la persona hasta que lo retire; VEXPay no lo devuelve por su cuenta. Acredita solo lo que debes.
• Los meses van en hora de Venezuela (America/Caracas).
• Un reembolso o contracargo de tarjeta sobre una de tus ventas se descuenta de tu saldo, aunque ya hayas acreditado ese dinero a tus usuarios finales. Recuperarlo de ellos te corresponde a ti.

Si algo sale mal

Relacionado: Receta: paga a tus usuarios · Registrar un vendedor · Comerciantes y payouts · Leer saldo y retenciones