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 en bolívares está disponible en tu saldo cuando el banco la confirma (mientras tanto, unconfirmedVes).

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 el banco aún no confirma queda en el pendingVes de la persona y pasa a availableVes cuando se confirman. Acreditar cuando las ventas ya están confirmadas 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".

Carga dinero que no es una venta (recargas)

Cuando el dinero que pagas viene de fuera de tus ventas (por ejemplo ingresos de publicidad), cárgalo a tu saldo con una recarga: envías un Pago Móvil a VEXPay y se acredita en tu saldo. VEXPay activa las recargas, con un límite mensual acordado contigo. Una recarga no es una venta: no dispara el webhook payment.completed y no cuenta como volumen de ventas.

1. 01
   Inicia la recarga

   POST /v1/balance/topups con amountVes, el payerPhone y la payerCedula desde los que vas a pagar, y una sourceNote que diga de dónde viene el dinero (mínimo 10 caracteres). O usa Portal → Balance movements → Load balance.

2. 02
   Envía el Pago Móvil

   Envía exactamente amountVes desde ese teléfono al receiver de la respuesta (código de banco, teléfono, documento) en menos de 15 minutos. En tu app bancaria elige el banco por su código.

3. 03
   Se completa sola

   GET /v1/balance/topups/:id pasa a completed cuando llega la transferencia. Se te acredita creditedVes = monto − comisión. Sigue la retención de saldo de tu cuenta, si la tiene (ninguna por defecto).

4. 04
   Opcional: disponible ya

   POST /v1/balance/topups/:id/instant si tu cuenta tiene retención, libera al momento la parte retenida por instantFeePercent de ella (instantFeeVes). Llamarlo otra vez no cobra nada más.

curl --request POST "${API_URL}/v1/balance/topups" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountVes": "100000.00",
    "payerPhone": "04121234567",
    "payerCedula": "V12345678",
    "sourceNote": "Ingresos de publicidad, segunda quincena de noviembre"
  }'
# → { "id": "...", "status": "pending", "amountVes": "100000.00", "expiresAt": "...",
#     "receiver": { "bankCode": "...", "phone": "...", "identification": "..." } }

• Cada recarga cuenta contra tu límite mensual (mes calendario de Venezuela, en dólares a tasa BCV, pendientes y completadas). Si lo superas: 422 topup_cap_exceeded con remainingUsd y remainingVes.
• Los bancos limitan cada Pago Móvil y cada día: carga un monto grande en varias recargas.
• Tu saldo muestra los movimientos topup, topup_fee, topup_instant_release y topup_instant_fee.
• Una transferencia que llega después de los 15 minutos no se acredita sola: contacta a VEXPay con la referencia.

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