Saldos, retenciones y payouts

Qué está disponible, qué está retenido y por qué, cómo funciona la retención de 24 h en cada moneda, cuánto cuestan los payouts y cómo conciliarlo todo.

Las partes de un saldo

Cada moneda (bolívares, USDT, USDC, pesos colombianos) tiene su propio saldo. Dentro de cada uno, tu dinero está en uno de estos estados:

Estado	Qué es	¿Se puede pagar?
Disponible	Dinero liberado que puedes retirar, pagar o convertir	Sí
Retenido	Acreditado en las últimas 24 horas (la retención del saldo)	Todavía no: pasa a disponible por sí solo
Reserva (solo Bs)	Un colchón de seguridad que VEX Pay define para tu cuenta, si aplica	No
Payout pendiente	Reservado por payouts que van en camino	Ya está saliendo

Bolívaresbash

curl "${API_URL}/v1/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
# availableVes = ledgerNetVes − reserveVes − heldVes

USDT / USDCbash

curl "${API_URL}/v1/crypto/balances" --header "x-api-key: ${VEXPAY_API_KEY}"
# cada uno: available, held, nextReleaseAt, pendingPayout (USDT además availableUsdt, heldUsdt)

Pesosbash

curl "${API_URL}/v1/cop/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
# availableCop, heldCop, nextReleaseAt, pendingPayoutCop

Cómo funciona la retención de 24 h

Cada crédito a tu saldo queda retenido balanceHoldHours (24 en cuentas Live, 0 en modo prueba) desde el momento en que se acredita. No hace falta hacer nada para liberarlo: en nextReleaseAt simplemente pasa a disponible.

Movimiento	¿Retenido 24 h?
Pagos completados (todos los métodos y monedas), descontando la comisión de VEXPay	Sí
USDT acreditados por una conversión	Solo la parte comprada con dinero que seguía retenido, hasta que termine esa retención original
Contracargos ganados y ajustes positivos	Sí
Dinero que regresa: payouts fallidos, conversiones canceladas, reversos de comisiones	No: vuelve exactamente como salió

Mientras el dinero está retenido, puedes…	Regla
Enviar payouts (banco, vendedor, wallet cripto)	No: los payouts solo usan dinero disponible
Convertir a USDT	Sí: los USDT quedan retenidos hasta que termine la retención original
Transferir a un vendedor	Sí: al vendedor no se le puede pagar antes de que termine la retención
Recibir reembolsos, reversos o contracargos	Sí: se descuentan primero del monto retenido

Cuando se rechaza un payout

Un payout mayor que la parte disponible responde 422 insufficient_balance con los montos que necesitas para decidir qué hacer:

422 insufficient_balancejson

{
  "error": "insufficient_balance",
  "availableVes": "3000.00",
  "requestedVes": "4000.00",
  "heldVes": "4342.50",
  "nextReleaseAt": "2026-10-20T00:48:52.784Z"
}

Envía ahora como máximo el monto disponible, o programa el resto para después de nextReleaseAt.
No reintentes en bucle: nada cambia hasta que termine una retención o llegue dinero nuevo.
Los payouts de USDT responden igual con availableUsdt, heldUsdt y nextReleaseAt; los payouts de COP de operaciones, con availableCop y heldCop.

Cuánto cuestan los payouts

Payout	Comisión
A tu propia cuenta bancaria (retiro inmediato)	Tu porcentaje en bolívares sobre el monto retirado
A tus vendedores verificados	Gratis (puede aplicar una comisión de payout a vendedores por acuerdo)
USDT a una wallet externa	La comisión de red + 0,25 USDT (p. ej. 1,00 USDT en BEP20, Polygon y Solana)
USDC a una wallet externa	0,75 USDC en BASE y Polygon (0,50 de comisión de red + 0,25)
A una de tus propias direcciones de depósito	Gratis: se liquida dentro de VEXPay

GET /v1/crypto/networks devuelve la comisión de payout exacta por red antes de enviar. La comisión se reserva junto con el monto y se devuelve si el payout falla.

Concílialo

Recorre los movimientos
GET /v1/balance/transactions lista cada movimiento en bolívares. La suma es igual a ledgerNetVes.
Ten en cuenta la retención
Los movimientos que siguen retenidos traen availableAt. La suma menos reserveVes menos heldVes es igual a availableVes.
Alerta ante diferencias
Si tu contabilidad no coincide, el movimiento que falta está en esa lista: identifícalo por id.