Listar movimientos del balance | Documentación API de Recurrente

curl -G https://app.recurrente.com/api/balance_transactions \
     -H "X-SECRET-KEY: <apiKey>" \
     -d from_time=2026-07-01 \
     -d until_time=2026-07-31 \
     -d currency=GTQ \
     -d type=charge

[
  {
    "id": "txn_ab12cd34",
    "account_id": "ac_merchant1",
    "type": "payout",
    "amount_in_cents": 10000,
    "net_amount_in_cents": 9440,
    "currency": "GTQ",
    "created_at": "2024-01-15T09:30:00Z",
    "source": {
      "type": "withdrawal",
      "id": "wi_ab12cd34"
    },
    "fee_in_cents": -560,
    "fee_details": [
      {
        "type": "processing",
        "amount_in_cents": -500
      }
    ],
    "description": "string",
    "balance_before_in_cents": 150000,
    "balance_after_in_cents": 100000
  }
]

amount_in_cents es el bruto y net_amount_in_cents es lo que efectivamente movió el balance; sumar fee_in_cents al bruto siempre da el neto. En un cobro, fee_details desglosa esa diferencia en la comisión y el IVA retenido, las mismas columnas del reporte descargable. balance_after_in_cents corresponde a la columna Balance de ese reporte.

Para conciliar un mes, filtra con from_time + until_time y sube items hasta 100. Cada par de fechas se envía completo: enviar solo una mitad devuelve 400 en vez de ignorar el rango.

No existe forma de preguntar qué cobros financiaron un retiro: Recurrente registra el débito del retiro y nada más, así que esa relación habría que inventarla. El camino inverso sí existe — cada movimiento en GET /api/transfers trae balance_transaction_id, la fila de ledger que registró.

Lista el ledger de la cuenta, del movimiento más reciente al más antiguo: es la forma API del estado de cuenta descargable. Los montos son firmados: positivo acredita el balance y negativo lo debita. `amount_in_cents` es el bruto y `net_amount_in_cents` es lo que efectivamente movió el balance; sumar `fee_in_cents` al bruto siempre da el neto. En un cobro, `fee_details` desglosa esa diferencia en la comisión y el IVA retenido, las mismas columnas del reporte descargable. `balance_after_in_cents` corresponde a la columna Balance de ese reporte. Para conciliar un mes, filtra con `from_time` + `until_time` y sube `items` hasta 100. Cada par de fechas se envía completo: enviar solo una mitad devuelve `400` en vez de ignorar el rango. No existe forma de preguntar qué cobros financiaron un retiro: Recurrente registra el débito del retiro y nada más, así que esa relación habría que inventarla. El camino inverso sí existe — cada movimiento en `GET /api/transfers` trae `balance_transaction_id`, la fila de ledger que registró.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Tu clave secreta de API. Una llave de cuenta (`sk_live_...`, `sk_test_...`) opera sobre su propia cuenta y, con `X-ACCOUNT-ID`, sobre sus cuentas conectadas. Una llave de organización (`sk_org_live_...`, `sk_org_test_...`) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con `X-ACCOUNT-ID`; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde `403` con `code: organization_key_unsupported`.

Query parameters

from_timedatetimeOptional

Inicio del rango de creación. Si se envía como fecha sin hora, se interpreta como el inicio del día. Se aplica solo junto con until_time.

until_timedatetimeOptional

Fin del rango de creación. Si se envía como fecha sin hora, se interpreta como el final del día. Se aplica solo junto con from_time.

currencystringOptional

Moneda del balance a consultar. Sin este filtro la lista mezcla todas las monedas de la cuenta.

typestringOptional

Tipo contable del movimiento, por ejemplo charge, payout, refund o dispute.

pageintegerOptional>=1Defaults to 1

Página a devolver. La respuesta trae los encabezados link, current-page, total-pages y total-count.

itemsintegerOptional1-100Defaults to 10

Elementos por página.

Response

Movimientos del balance

idstring

ID público del movimiento del balance. Los movimientos registrados antes de que el ledger fuera público conservan el prefijo ba_; trata el ID como opaco.

account_idstring

Cuenta cuyo balance cambió

typestring

Tipo contable del movimiento

amount_in_centsinteger

Monto bruto firmado en centavos; positivo acredita y negativo debita

net_amount_in_centsinteger

Monto firmado que efectivamente movió el balance

currencystring

Moneda del balance

created_atdatetime

Momento en que el movimiento fue registrado

sourceobject or nullOptional

Recurso que originó el movimiento, cuando existe

fee_in_centsintegerOptional

Lo retenido sobre el bruto, firmado. Sumado a amount_in_cents da net_amount_in_cents

fee_detailslist of objectsOptional

Desglose de fee_in_cents con los componentes que registramos en la moneda del movimiento. Lo que no aparezca aquí sigue contando dentro del total

descriptionstring or nullOptional

Descripción opcional del movimiento

balance_before_in_centsinteger or nullOptional

Snapshot del balance antes del movimiento, cuando está disponible

balance_after_in_centsinteger or nullOptional

Snapshot del balance después del movimiento; equivale a la columna Balance del reporte descargable

Errors

400

Bad Request Error

Para conciliar un mes, filtra con from_time + until_time y sube items hasta 100. Cada par de fechas se envía completo: enviar solo una mitad devuelve 400 en vez de ignorar el rango.