Saldo y recargas

Consultar el saldo prepago de Trevol, ver sus movimientos y preparar una recarga con Wompi por la API.

El saldo prepago es de la cuenta, no de la empresa: todas las empresas de la cuenta lo comparten (shared: true). Solo lo que se emite en producción (llaves tvl_live_…) lo consume; la habilitación no cobra. Con available por debajo del precio de un documento, emitir en producción responde insufficient_balance (402).

El saldo

Cualquier llave lo lee, de lectura o de escritura, de Pruebas o de Producción: es uno solo.

GET /v1/balance

cURL

curl "https://api.trevol.si/v1/balance" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Respuesta200 OK

{
  "object": "balance",
  "currency": "COP",
  "available": 48600,
  "held": 400,
  "overdraft": 0,
  "low_threshold": 10000,
  "level": "ok",
  "updated_at": "2026-10-31T09:20:05-05:00",
  "shared": true
}

Campo	Qué es
`available`	Lo que se puede gastar, en pesos (puede ser negativo por un cobro tardío).
`held`	Lo apartado por documentos que la DIAN todavía valida.
`overdraft`	Cuánto puede bajar `available` de cero al apartar un documento.
`low_threshold`	El umbral del aviso de saldo bajo (20 % de la última recarga); `null` sin recargas.
`level`	`empty` (`available` ≤ 0), `low` (por debajo del umbral) u `ok`.

El evento balance.low avisa por webhook cuando el saldo baja del umbral (solo en producción).

Los movimientos

Lo mismo que «Saldo y recargas» en la app: un documento es una fila; lo demás, una fila por movimiento. Filtra con type (all, documents, funding o top_ups) y pagina con limit y starting_after (Paginación).

GET /v1/balance/transactions

cURL

curl "https://api.trevol.si/v1/balance/transactions?limit=100" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Respuesta200 OK

{
  "object": "list",
  "has_more": true,
  "next_cursor": "btx_9300",
  "data": [
    {
      "id": "btx_9341",
      "object": "balance_transaction",
      "type": "document",
      "status": "pending",
      "amount": -400,
      "available_after": 48600,
      "description": "Factura FE1290 · apartado mientras la DIAN lo valida",
      "document": {
        "type": "invoice",
        "number": "FE1290"
      },
      "company": {
        "nit": "900373115",
        "name": "TOSTADORA MONTEVERDE SAS"
      },
      "reference": null,
      "created_at": "2026-10-31T09:20:05-05:00"
    },
    {
      "id": "btx_9338",
      "object": "balance_transaction",
      "type": "document",
      "status": "charged",
      "amount": -400,
      "available_after": 49000,
      "description": "Nómina NE15",
      "document": {
        "type": "payroll",
        "number": "NE15"
      },
      "company": {
        "nit": "900373591",
        "name": "CAFÉ DEL VALLE SAS"
      },
      "reference": null,
      "created_at": "2026-10-31T08:02:41-05:00"
    },
    {
      "id": "btx_9301",
      "object": "balance_transaction",
      "type": "document",
      "status": "released",
      "amount": 0,
      "available_after": 49000,
      "description": "Factura FE1289 · rechazado por la DIAN: no se cobró",
      "document": {
        "type": "invoice",
        "number": "FE1289"
      },
      "company": {
        "nit": "900373115",
        "name": "TOSTADORA MONTEVERDE SAS"
      },
      "reference": null,
      "created_at": "2026-10-30T17:10:00-05:00"
    },
    {
      "id": "btx_9300",
      "object": "balance_transaction",
      "type": "top_up",
      "status": "completed",
      "amount": 50000,
      "available_after": 49400,
      "description": "Recarga TRV-REC-20261030-8F2A61C0D9B3",
      "document": null,
      "company": null,
      "reference": "TRV-REC-20261030-8F2A61C0D9B3",
      "created_at": "2026-10-30T16:58:12-05:00"
    }
  ]
}

Recargar

POST /v1/balance/top_ups prepara una recarga y devuelve lo que necesita el widget de Wompi (WidgetCheckout): la referencia, el monto, la firma de integridad y su vencimiento. El pago se hace en el widget; cuando Wompi lo aprueba, Trevol abona el saldo.

POST /v1/balance/top_ups

cURL

curl -X POST "https://api.trevol.si/v1/balance/top_ups" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cop": 50000
}'

Probar en el Playground

Respuesta201 Created

{
  "object": "top_up",
  "reference": "TRV-REC-20261031-4C1D2E3F4A5B",
  "amount_cop": 50000,
  "status": "prepared",
  "wompi": {
    "public_key": "pub_prod_Ejemplo0000000000000000000000",
    "reference": "TRV-REC-20261031-4C1D2E3F4A5B",
    "amount_in_cents": 5000000,
    "currency": "COP",
    "signature": "5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d",
    "expiration_time": "2026-10-31T15:20:05.000Z"
  }
}

Es dinero real con cualquier llave, también tvl_test_: no hay un saldo de pruebas.
Solo llaves de escritura; exige Idempotency-Key (repetir con la misma clave devuelve la misma recarga). La firma vence en una hora: si el widget venció, prepara otra.
El monto va entre la recarga mínima y la máxima (top_up_below_minimum y top_up_above_maximum, con minimum_cop y maximum_cop). Si Wompi no está disponible: top_ups_unavailable.
La factura de la recarga sale a nombre de buyer; sin él, a nombre de la empresa de la llave con sus datos. Si no alcanzan, 422 en buyer.*.
Hasta 20 por llave cada 10 minutos.

Referencia: Saldo.