Lee tu saldo y tus retenciones

Averigua cuánto puedes retirar ahora en cada moneda, cuándo se libera el dinero retenido 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 créditos Live nuevos quedan retenidos 24 horas y luego pasan a disponibles solos: no hace falta hacer nada y no llega ningún webhook cuando ocurre. Solo el dinero disponible se puede retirar.

Pasos

Lee el saldo en bolívares
GET /v1/balance. availableVes es lo que puedes retirar ahora; heldVes y nextReleaseAt te dicen qué viene y cuándo; reserveVes es un colchón que VEXPay puede definir para tu cuenta.
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. 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 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	Sigue retenido	Espera a `nextReleaseAt`; retira ahora la parte disponible.
Los USDT convertidos siguen retenidos	Convertiste dinero que seguía retenido; los USDT conservan la hora de liberación original	Espera a `nextReleaseAt` en el saldo USDT.
`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.
El dinero del vendedor no se libera aunque su retención es 0	Tu propia retención de 24 horas sobre esos fondos sigue aplicando	Espera a que termine.

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