Lee tu saldo y tus retenciones

Averigua cuánto puedes retirar ahora en cada moneda, qué espera la confirmación del banco, cómo funciona la liquidación automática y cómo conciliar tus libros con la lista de movimientos.

Qué vas a hacer

Cada moneda (bolívares, USDT, USDC, pesos) tiene su propio saldo. Los pagos Live en bolívares esperan a que el banco los confirme y luego pasan a disponibles solos: no hace falta hacer nada y no llega ningún webhook cuando ocurre. Los USDT y los pesos están disponibles de inmediato. Solo el dinero disponible se puede retirar, y en modo Live los bolívares disponibles se liquidan a tu cuenta de payout verificada automáticamente cada 15 minutos.

Pasos

Lee el saldo en bolívares
GET /v1/balance. availableVes es lo que puedes retirar ahora; unconfirmedVes espera al banco; heldVes y nextReleaseAt solo aplican si tu cuenta tiene retención; reserveVes es un colchón que VEXPay puede definir para tu cuenta; settlement dice si la liquidación automática está activa.
Lee stablecoins y pesos
GET /v1/crypto/balances (o GET /v1/crypto/balance?currency=USDC) devuelve available, held, nextReleaseAt y pendingPayout por moneda. GET /v1/cop/balance devuelve availableCop, heldCop, nextReleaseAt y pendingPayoutCop.
Marketplaces: lee los saldos de vendedores
GET /v1/merchants/:id/balance devuelve pendingVes y availableVes del vendedor (más un bloque cop cuando tiene actividad en pesos). Los totales de la plataforma están en GET /v1/balance.
Concilia los bolívares
Recorre GET /v1/balance/transactions (limit hasta 100, cursor desde nextCursor). Cada movimiento tiene un id estable, un amountVes con signo y availableAt mientras está retenido. Las liquidaciones automáticas son payouts con un externalRef que empieza con auto_settle_. Filtra por type, paymentId, payoutId, from y to.

Saldosbash

curl "${API_URL}/v1/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
curl "${API_URL}/v1/crypto/balances" --header "x-api-key: ${VEXPAY_API_KEY}"
curl "${API_URL}/v1/cop/balance" --header "x-api-key: ${VEXPAY_API_KEY}"

Movimientosbash

curl "${API_URL}/v1/balance/transactions?limit=100&from=2026-11-01T00:00:00Z" \
  --header "x-api-key: ${VEXPAY_API_KEY}"
# Repite con &cursor=<nextCursor> hasta que nextCursor sea null.

Comprueba que funcionó

Tus libros cuadran cuando, sumando todas las páginas, el total de amountVes es igual a ledgerNetVes, y ledgerNetVes − reserveVes − heldVes − unconfirmedVes es igual a availableVes. El portal muestra las mismas cifras en Overview, Payouts, Balance movements, USDT y COP.

Si algo sale mal

Síntoma	Causa probable	Qué hacer
El dinero aparece pero no se puede retirar	El banco aún no confirma el pago (`unconfirmedVes`)	Retira ahora la parte disponible; el resto sigue cuando el banco lo confirme.
La liquidación automática no corre	No hay cuenta de payout verificada, el monto está bajo el mínimo o está desactivada para tu cuenta	Lee `settlement.status` en `GET /v1/balance`.
`availableVes` está en negativo	Un contracargo de tarjeta fue mayor que tu saldo disponible	Los pagos nuevos lo recargan; los payouts y conversiones esperan hasta entonces.
Tus libros no cuadran	Se perdió un movimiento (contracargo, reverso, ajuste)	Recorre los movimientos y compara cada uno por `id`.
403 `method_not_allowed` en el saldo USDC o COP	Esa moneda no está habilitada para ti	Pregunta a VEXPay.

Relacionado: Saldos y retenciones · Concilia tu saldo · Retirar tu saldo