# Ledger transactions Retrieve a paginated list of ledger transactions within a specified UTC date-time range. Each entry includes the available balance before and after the ledger entry is applied, so you can reconcile balance changes over time for a given currency. ## Key features and functionality * **Complete results for the requested range:** Returns ledger debits/credits within the date/time range you specify (UTC). * **Reconciliation support:** Each transaction includes `availableBalanceBefore` and `availableBalanceAfter` to help track the running balance changes. * **Detailed line items:** Includes transaction amount, currency, operation, status, timestamps, and source system. * **Filtering and search:** Filter by currency, time range, status, or an exact transaction reference (`txnReference`). * **Pagination and sorting:** Offset-based pagination (page-size, offset) and optional sorting (sort-key, sort-direction). * **Format options:** Supports both **JSON** (default) and **CSV** output formats via the `Accept` header. | Parameter | Description | Req/Opt | | --- | --- | --- | | `currency` | Three-letter ISO 4217 currency code (e.g., USD) | Required | | `start-dttm` | Start of the date/time range (inclusive, UTC). | Required | | `end-dttm` | End of the date/time range (exclusive, UTC) | Required | | `page-size` | Number of records per page (default: 25, max: 50). | Required | | `offset` | Number of records to skip before returning results | Optional | | `status` | Filter by transaction status (SUCCESS; PENDING reserved for future use). | Optional | | `txnReference` | Filter by an exact transaction reference (external reference). For payments, the txnReference value is the paymentId. | Optional | | `sort-key` | Sort field. Allowed values include: CREATED_ATSTATEMENT_OPERATIONSTATEMENT_SOURCESTATEMENT_STATUSSTATEMENT_TXN_REFERENCESTATEMENT_UPDATED_AT | Optional | | `sort-direction` | Sort direction: ASC or DESC | Optional | ## Operations The following table provides information about ledger operations, which are actions applied to your prefunded ledger account that affect available funds and/or reserved funds. | Operation | Definition | Behavior | | --- | --- | --- | | `CREDIT` | Adds funds to the ledger account. | Increases `availableBalance` (spendable funds). | | `RESERVE` | Moves funds from **available** to **reserved** for an in-flight payment. | Decreases `availableBalance`, because those funds are no longer spendable while the payment is pending/processing. | | `DEBIT` | Finalizes a payment by consuming funds that were previously reserved. | Often does not change `availableBalance` because the reduction in spendable funds already occurred at `RESERVE` time. This operation typically reduces the (separate) reserved amount and records the consumption of that reservation. | | `RELEASE` | Cancels a reservation and returns reserved funds back to **available**. | Increases `availableBalance` (funds become spendable again). | | `VOID_BALANCE` | Administrative action that invalidates a previously recorded balance (or balance state) due to an error or exception. | Implementation-specific operation; may **reset**, **nullify**, or **mark a balance state as void** for reconciliation and/or audit correction workflows. | | `OVERRIDE_BALANCE` | Administrative action that forcibly sets the balance to a corrected value. | Implementation-specific operation; typically **replaces the calculated balance** to correct discrepancies. | | `VOID_PREFUND_BALANCE` *(Deprecated)* | Deprecated predecessor to `VOID_BALANCE`. No longer generated for new transactions, but may appear in historical ledger records for legacy entries. | Treat the same as `VOID_BALANCE` for reconciliation purposes. | | `OVERRIDE_PREFUND_BALANCE` *(Deprecated)* | Deprecated predecessor to `OVERRIDE_BALANCE`. No longer generated for new transactions, but may appear in historical ledger records for legacy entries. | Treat the same as `OVERRIDE_BALANCE` for reconciliation purposes. | RESERVE and DEBIT Operations Available balance represents funds that are currently spendable (not reserved). When a payment begins, the system may reserve funds first to prevent double-spending while the payment is in-flight. This is why `RESERVE` reduces `availableBalance`. When the payment completes, the system debits from the reserved amount (finalizes the outflow). Because these funds were already removed from **available** during `RESERVE`, the `DEBIT` may leave `availableBalance` unchanged. If the payment fails or is canceled, `RELEASE` returns reserved funds back to **available**, increasing `availableBalance` again. Reserve balance The **Get ledger transactions** operation reports changes to available (spendable) balance alongside transaction activity. Reserved funds may not be shown as a separate balance field. Instead, reservations appear as `RESERVE`/`RELEASE`/`DEBIT` operations that explain why available balance moved (or did not move). ## Transaction Source For each transaction listed in the response, the `txnSource` field indicates the source of the ledger transaction, which system or flow created the transaction. The following table lists the values for the `txnSource` field. | Source | Definition | Occurrence | Notes | | --- | --- | --- | --- | | `PAYMENTS` | Created by a payments flow that impacts your prefunded ledger (for example, reserving funds, debiting reserved funds, releasing a reservation). | When a payment lifecycle event results in a ledger entry. | Often pairs with `RESERVE`, `DEBIT`, or `RELEASE`, but can also appear with `CREDIT` depending on the flow. | | `BANK` | Created by a bank-related funding or movement that impacts your prefunded ledger balance. | When funds move between banking rails and the prefunded ledger. | Use amount, operation, timestamps, and your external reference fields to reconcile with bank-side records. | | `POSTED_PAYMENT` | Created when a payment is formally posted/recorded to the ledger as part of payment processing. | When the system records a “posted” payment event to the ledger. | This is about the origin of the entry (posting step), not necessarily the final payment status. | | `CREDIT_MEMO` | Created by a credit memo event (for example, a credit applied to your ledger outside the normal payment flow). | Corrections, adjustments, or credits that are represented as credit memos. | Important for reconciliation and accounting notes. | | `MANUAL` | Created manually (for example, via an administrative API action). | Exceptional cases: operational corrections or support actions. | If you see `MANUAL` and need details, contact Ripple Technical Services with the `txnReference` and timestamps. | Transaction source `txnSource` tells you **which system or process created the ledger entry**. It does not, by itself, indicate whether funds were added or removed. This is indicated by the operation (`CREDIT`/`DEBIT`/`RESERVE`/`RELEASE`) and amount. ## Example request To request a **CSV** file, you must provide the `Accept: text/csv` header. If this header is omitted, the API returns **JSON** by default. **Requesting CSV (Recommended for reconciliation)** ```bash curl -X GET "[https://api.ripple.com/v2/ledger-transactions?currency=USD&page-size=10&start-dttm=2025-02-27T08:30:00Z&end-dttm=2025-12-27T08:30:00Z](https://api.ripple.com/v2/ledger-transactions?currency=USD&page-size=10&start-dttm=2025-02-27T08:30:00Z&end-dttm=2025-12-27T08:30:00Z)" \ -H "Authorization: Bearer " \ -H "Accept: text/csv" ``` **Requesting JSON (Default)** ```bash curl -X GET "[https://api.ripple.com/v2/ledger-transactions?currency=USD&page-size=10&start-dttm=2025-02-27T08:30:00Z&end-dttm=2025-12-27T08:30:00Z](https://api.ripple.com/v2/ledger-transactions?currency=USD&page-size=10&start-dttm=2025-02-27T08:30:00Z&end-dttm=2025-12-27T08:30:00Z)" \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` ## Example response **CSV response** ```csv tenant,amount,currency,operation,txnSource,status,createdDttm,updatedDttm,availableBalanceBefore,availableBalanceAfter rpd2demo,2.06,USD,DEBIT,PAYMENTS,SUCCESS,2025-12-12T23:08:23.399345535Z,2025-12-12T23:08:23.399345704Z,1140833.98234594,1140833.98234594 rpd2demo,30,USD,DEBIT,PAYMENTS,SUCCESS,2025-12-12T23:08:01.260806899Z,2025-12-12T23:08:01.260807099Z,1140833.98234594,1140833.98234594 rpd2demo,30,USD,DEBIT,PAYMENTS,SUCCESS,2025-12-12T23:06:59.979143148Z,2025-12-12T23:06:59.979143319Z,1140833.98234594,1140833.98234594 rpd2demo,30,USD,RESERVE,PAYMENTS,SUCCESS,2025-12-12T23:06:34.692569101Z,2025-12-12T23:06:34.692569611Z,1140863.98234594,1140833.98234594 ``` **JSON response** ```json { "offset": "0", "pageSize": "10", "pageElements": "10", "total": "10000", "statementTransactions": [ { "tenant": "rpd2demo", "amount": "2.06", "currency": "USD", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T23:08:23.399345535Z", "updatedDttm": "2025-12-12T23:08:23.399345704Z", "availableBalanceBefore": "1140833.98234594", "availableBalanceAfter": "1140833.98234594" }, { "tenant": "rpd2demo", "amount": "30", "currency": "USD", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T23:08:01.260806899Z", "updatedDttm": "2025-12-12T23:08:01.260807099Z", "availableBalanceBefore": "1140833.98234594", "availableBalanceAfter": "1140833.98234594" }, { "tenant": "rpd2demo", "amount": "30", "currency": "USD", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T23:06:59.979143148Z", "updatedDttm": "2025-12-12T23:06:59.979143319Z", "availableBalanceBefore": "1140833.98234594", "availableBalanceAfter": "1140833.98234594" }, { "tenant": "rpd2demo", "amount": "30", "currency": "USD", "operation": "RESERVE", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T23:06:34.692569101Z", "updatedDttm": "2025-12-12T23:06:34.692569611Z", "availableBalanceBefore": "1140863.98234594", "availableBalanceAfter": "1140833.98234594" }, { "tenant": "rpd2demo", "amount": "30", "currency": "USD", "operation": "RESERVE", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T23:06:34.365931233Z", "updatedDttm": "2025-12-12T23:06:34.365931493Z", "availableBalanceBefore": "1140893.98234594", "availableBalanceAfter": "1140863.98234594" }, { "tenant": "rpd2demo", "amount": "2.06", "currency": "USD", "operation": "RESERVE", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T23:06:32.698258841Z", "updatedDttm": "2025-12-12T23:06:32.698259061Z", "availableBalanceBefore": "1140896.04234594", "availableBalanceAfter": "1140893.98234594" }, { "tenant": "rpd2demo", "amount": "2.06", "currency": "USD", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T22:36:27.081413406Z", "updatedDttm": "2025-12-12T22:36:27.081413636Z", "availableBalanceBefore": "1140896.04234594", "availableBalanceAfter": "1140896.04234594" }, { "tenant": "rpd2demo", "amount": "30", "currency": "USD", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T22:36:01.633919258Z", "updatedDttm": "2025-12-12T22:36:01.633919449Z", "availableBalanceBefore": "1140896.04234594", "availableBalanceAfter": "1140896.04234594" }, { "tenant": "rpd2demo", "amount": "30", "currency": "USD", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T22:34:59.583176108Z", "updatedDttm": "2025-12-12T22:34:59.583176388Z", "availableBalanceBefore": "1140896.04234594", "availableBalanceAfter": "1140896.04234594" }, { "tenant": "rpd2demo", "amount": "30", "currency": "USD", "operation": "RESERVE", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-12-12T22:34:36.116270734Z", "updatedDttm": "2025-12-12T22:34:36.116270934Z", "availableBalanceBefore": "1140926.04234594", "availableBalanceAfter": "1140896.04234594" } ] } ```