> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.recurrente.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server. # Listar movimientos del balance GET https://app.recurrente.com/api/balance_transactions 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ó. Reference: https://docs.recurrente.com/referencia-api/api-reference/balance-transactions/list-balance-transactions ## Authentication - `X-SECRET-KEY` header (required) — 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. La llave también fija el ambiente: una `sk_test_` solo lista y resuelve objetos de prueba (`live_mode: false`) y una `sk_live_` solo objetos reales. Un ID del otro ambiente responde `404` (`401` en `/customers`). 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`. ## Request ### Query parameters - `from_time` (datetime, optional) — 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_time` (datetime, optional) — 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`. - `currency` (string, optional) — Moneda del balance a consultar. Sin este filtro la lista mezcla todas las monedas de la cuenta. - `type` (string, optional) — Tipo contable del movimiento, por ejemplo `charge`, `payout`, `refund` o `dispute`. - `page` (integer, optional, default: 1) — Página a devolver. La respuesta trae los encabezados `link`, `current-page`, `total-pages` y `total-count`. - `items` (integer, optional, default: 10) — Elementos por página. ## Response ### 200 Movimientos del balance - `list of BalanceTransaction` ## Errors ### 400 Bad Request Error Rango de fechas incompleto - `message` (string, optional) — Mensaje de error - `code` (string, optional) — Código estable legible por máquinas, cuando aplica - `refund_id` (string, optional) — ID del reembolso relacionado cuando aplica - `endpoint` (string, optional) — Acción de API rechazada, cuando aplica - `errors` (ErrorErrors, optional) — Detalles de errores por campo ## Types ### BalanceTransaction Movimiento inmutable del ledger de una cuenta. Los montos son firmados. Un `type: payout` con `source.type: withdrawal` representa el débito del retiro, no la composición de fondos que lo financió. En un retiro, el balance se debita por el monto bruto; lo que llega al banco es el `net_amount_in_cents` del movimiento en `GET /api/transfers`, que descuenta la comisión de retiro. - `id` (string, required) — 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_id` (string, required) — Cuenta cuyo balance cambió - `type` (string, required) — Tipo contable del movimiento - `amount_in_cents` (integer, required) — Monto bruto firmado en centavos; positivo acredita y negativo debita - `net_amount_in_cents` (integer, required) — Monto firmado que efectivamente movió el balance - `currency` (string, required) — Moneda del balance - `created_at` (datetime, required) — Momento en que el movimiento fue registrado - `source` (BalanceTransactionSource, optional, nullable) — Recurso que originó el movimiento, cuando existe - `fee_in_cents` (integer, optional) — Lo retenido sobre el bruto, firmado. Sumado a `amount_in_cents` da `net_amount_in_cents` - `fee_details` (list of BalanceTransactionFeeDetailsItems, optional) — 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 - `description` (string, optional, nullable) — Descripción opcional del movimiento - `balance_before_in_cents` (integer, optional, nullable) — Snapshot del balance antes del movimiento, cuando está disponible - `balance_after_in_cents` (integer, optional, nullable) — Snapshot del balance después del movimiento; equivale a la columna Balance del reporte descargable ### ErrorErrors Detalles de errores por campo ### BalanceTransactionSource Recurso que originó el movimiento, cuando existe - `type` (string, optional) - `id` (string, optional) — ID público de la fuente, cuando ese tipo de recurso lo expone ### BalanceTransactionFeeDetailsItems - `type` (enum, optional) - Allowed values: `processing`, `vat_withholding`, `tax_invoicing` - `amount_in_cents` (integer, optional) ## Examples **Response** ```json [ { "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 } ] ``` **SDK Code** ```python import requests url = "https://app.recurrente.com/api/balance_transactions" querystring = {"from_time":"2026-07-01","until_time":"2026-07-31","currency":"GTQ","type":"charge"} headers = {"X-SECRET-KEY": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://app.recurrente.com/api/balance_transactions?from_time=2026-07-01&until_time=2026-07-31¤cy=GTQ&type=charge'; const options = {method: 'GET', headers: {'X-SECRET-KEY': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://app.recurrente.com/api/balance_transactions?from_time=2026-07-01&until_time=2026-07-31¤cy=GTQ&type=charge" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-SECRET-KEY", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://app.recurrente.com/api/balance_transactions?from_time=2026-07-01&until_time=2026-07-31¤cy=GTQ&type=charge") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-SECRET-KEY"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://app.recurrente.com/api/balance_transactions?from_time=2026-07-01&until_time=2026-07-31¤cy=GTQ&type=charge") .header("X-SECRET-KEY", "") .asString(); ``` ```php request('GET', 'https://app.recurrente.com/api/balance_transactions?from_time=2026-07-01&until_time=2026-07-31¤cy=GTQ&type=charge', [ 'headers' => [ 'X-SECRET-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://app.recurrente.com/api/balance_transactions?from_time=2026-07-01&until_time=2026-07-31¤cy=GTQ&type=charge"); var request = new RestRequest(Method.GET); request.AddHeader("X-SECRET-KEY", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["X-SECRET-KEY": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://app.recurrente.com/api/balance_transactions?from_time=2026-07-01&until_time=2026-07-31¤cy=GTQ&type=charge")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```