Saldos, retenciones y payouts

Qué está disponible, qué espera la confirmación del banco y por qué, cómo funciona la liquidación automática, 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í
Pendiente de confirmación del banco (solo Bs)	Pagos en bolívares que el banco aún no confirma (`unconfirmedVes`)	Todavía no: pasa a disponible por sí solo cuando el banco lo confirma
Retenido	Una retención de saldo que VEX Pay definió para tu cuenta, si aplica (ninguna por defecto)	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 − unconfirmedVes

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

Confirmación del banco (sin retención de 24 h)

Por defecto no hay retención por tiempo (balanceHoldHours es 0). Un pago en bolívares cuenta en availableVes cuando el banco confirma que el dinero llegó; mientras tanto está en unconfirmedVes. No tienes que hacer nada y no llega ningún webhook cuando se confirma. Los USDT y los pesos están disponibles en cuanto se acreditan, salvo los USDT comprados (convertidos) con bolívares que aún esperan la confirmación del banco: aparecen como retenidos (heldUsdt, sin nextReleaseAt) y pasan a disponibles cuando el banco confirma cada pago con el que se pagaron.

Movimiento	¿Espera al banco?
Pagos en bolívares completados, descontando la comisión de VEXPay	Sí: hasta que el banco confirma el pago
Pagos en bolívares que el banco no encuentra	Sí: quedan fuera del disponible hasta que VEXPay los resuelva
Pagos en USDT, USDC y pesos	No
Dinero que regresa: payouts fallidos, conversiones canceladas, reversos de comisiones	No: vuelve exactamente como salió

Mientras los bolívares esperan al banco, puedes…	Regla
Enviar payouts a tu banco o a un vendedor	No: los payouts solo usan dinero confirmado por el banco
Convertir a USDT	Sí
Transferir a un vendedor	Sí
Reembolsar o reversar el pago	Sí, si tu saldo lo cubre

Liquidación automática

En modo Live, cada 15 minutos VEXPay envía tus bolívares disponibles a tu cuenta de payout verificada en un payout inmediato — dos cuando tu saldo llegó por más de un banco, porque cada payout sale en una sola transferencia. Sigue el mismo camino que POST /v1/payouts/instant: aplica tu comisión de payout inmediato, el payout aparece en GET /v1/payouts y recibes los webhooks payout.* de siempre.

Detalle	Valor
Qué se envía	Todo `availableVes`, en hasta dos payouts por corrida; cada uno se envía cuando alcanza el mínimo (`settlement.minimumVes`, Bs 100,00 por defecto) y una parte menor espera a una corrida siguiente
Cómo reconocerlo	`externalRef` empieza con `auto_settle_`; el concepto en el banco dice “Liquidacion VEX Pay”
Si falla	El dinero vuelve a tu saldo y la siguiente corrida lo intenta de nuevo
Sin cuenta de payout verificada	No se envía nada; tu saldo se queda hasta que agregues y verifiques una
Tu estado	`settlement` en `GET /v1/balance`: `enabled` y `status` (por ejemplo `active`, `no_payout_account`, `opted_out`, `test_mode`)

Puedes seguir retirando tú entre corridas con POST /v1/payouts/instant. Las cuentas que pagan a vendedores o dispersiones desde su saldo pueden pedir a VEXPay que desactive la liquidación automática.

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": "0.00",
  "unconfirmedVes": "4342.50",
  "nextReleaseAt": null,
  "maxPayoutVes": "3000.00"
}

Envía ahora como máximo el monto disponible. unconfirmedVes pasa a disponible a medida que el banco confirma cada pago.
Un payout en Bs sale como una sola transferencia bancaria y nunca se divide, así que lo máximo que acepta un solo payout es maxPayoutVes, que puede ser menor que availableVes. Envía ese monto y luego el resto en un segundo payout.
No reintentes en bucle: nada cambia hasta que el banco confirme un pago 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 payout de la red, que muestra GET /v1/crypto/networks
USDC a una wallet externa	La comisión de payout de la red, que muestra GET /v1/crypto/networks
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 confirmación del banco
La suma menos reserveVes menos heldVes menos unconfirmedVes es igual a availableVes. Las liquidaciones automáticas son payouts con un externalRef que empieza con auto_settle_.
Alerta ante diferencias
Si tu contabilidad no coincide, el movimiento que falta está en esa lista: identifícalo por id.