# Transações do ledger Recupere uma lista paginada de transações do ledger dentro de um intervalo de data e hora em UTC. Cada lançamento inclui o saldo disponível antes e depois da aplicação do lançamento, para que você possa conciliar as variações de saldo ao longo do tempo em uma determinada moeda. ## Principais recursos e funcionalidades * **Resultados completos do intervalo solicitado:** retorna os débitos/créditos do ledger dentro do intervalo de data e hora que você especificar (UTC). * **Apoio à conciliação:** cada transação inclui `availableBalanceBefore` e `availableBalanceAfter` para ajudar a acompanhar a variação do saldo corrente. * **Itens detalhados:** inclui valor da transação, moeda, operação, status, timestamps e sistema de origem. * **Filtros e busca:** filtre por moeda, intervalo de tempo, status ou uma referência de transação exata (`txnReference`). * **Paginação e ordenação:** paginação por offset (page-size, offset) e ordenação opcional (sort-key, sort-direction). * **Opções de formato:** aceita os formatos de saída **JSON** (padrão) e **CSV** pelo cabeçalho `Accept`. | Parâmetro | Descrição | Obrig./Opc. | | --- | --- | --- | | `currency` | Código de moeda ISO 4217 de três letras (por exemplo, USD) | Obrigatório | | `start-dttm` | Início do intervalo de data e hora (inclusivo, UTC). | Obrigatório | | `end-dttm` | Fim do intervalo de data e hora (exclusivo, UTC) | Obrigatório | | `page-size` | Número de registros por página (mín.: 1, máx.: 50). | Obrigatório | | `offset` | Número de registros a pular antes de retornar resultados | Opcional | | `status` | Filtra pelo status da transação (SUCCESS; PENDING reservado para uso futuro). | Opcional | | `txnReference` | Filtra por uma referência de transação exata (referência externa). Para pagamentos, o valor de txnReference é o paymentId. | Opcional | | `sort-key` | Campo de ordenação. Os valores permitidos incluem: CREATED_ATSTATEMENT_OPERATIONSTATEMENT_SOURCESTATEMENT_STATUSSTATEMENT_TXN_REFERENCESTATEMENT_UPDATED_AT | Opcional | | `sort-direction` | Direção da ordenação: ASC ou DESC | Opcional | ## Operações A tabela a seguir traz informações sobre as operações de ledger, que são ações aplicadas à sua conta de ledger pré-financiada e que afetam os recursos disponíveis e/ou reservados. | Operação | Definição | Comportamento | | --- | --- | --- | | `CREDIT` | Adiciona recursos à conta do ledger. | Aumenta o `availableBalance` (recursos utilizáveis). | | `RESERVE` | Move recursos de **disponível** para **reservado** por causa de um pagamento em andamento. | Diminui o `availableBalance`, porque esses recursos deixam de ser utilizáveis enquanto o pagamento está pendente ou em processamento. | | `DEBIT` | Conclui um pagamento consumindo recursos que haviam sido reservados. | Em geral não altera o `availableBalance`, porque a redução dos recursos utilizáveis já ocorreu no momento do `RESERVE`. Esta operação normalmente reduz o valor reservado (que é separado) e registra o consumo dessa reserva. | | `RELEASE` | Cancela uma reserva e devolve os recursos reservados para **disponível**. | Aumenta o `availableBalance` (os recursos voltam a ser utilizáveis). | | `VOID_BALANCE` | Ação administrativa que invalida um saldo (ou estado de saldo) registrado anteriormente por causa de um erro ou exceção. | Operação que depende da implementação; pode **redefinir**, **anular** ou **marcar um estado de saldo como nulo** em fluxos de conciliação e/ou correção de auditoria. | | `OVERRIDE_BALANCE` | Ação administrativa que força o saldo para um valor corrigido. | Operação que depende da implementação; normalmente **substitui o saldo calculado** para corrigir divergências. | Operações RESERVE e DEBIT O saldo disponível representa os recursos que podem ser usados no momento (não reservados). Quando um pagamento começa, o sistema pode reservar recursos antes, para evitar gasto duplo enquanto o pagamento está em andamento. É por isso que o `RESERVE` reduz o `availableBalance`. Quando o pagamento é concluído, o sistema debita do valor reservado (finaliza a saída). Como esses recursos já haviam saído de **disponível** durante o `RESERVE`, o `DEBIT` pode deixar o `availableBalance` inalterado. Se o pagamento falhar ou for cancelado, o `RELEASE` devolve os recursos reservados para **disponível**, aumentando novamente o `availableBalance`. Saldo reservado A operação **Get ledger transactions** informa as variações do saldo disponível (utilizável) junto com a atividade de transações. Os recursos reservados podem não aparecer como um campo de saldo separado. Em vez disso, as reservas aparecem como operações `RESERVE`/`RELEASE`/`DEBIT` que explicam por que o saldo disponível variou (ou não). ## Origem da transação Para cada transação listada na resposta, o campo `txnSource` indica a origem da transação de ledger, ou seja, qual sistema ou fluxo a criou. A tabela a seguir lista os valores do campo `txnSource`. | Origem | Definição | Ocorrência | Observações | | --- | --- | --- | --- | | `PAYMENTS` | Criada por um fluxo de pagamentos que afeta o seu ledger pré-financiado (por exemplo, reservar recursos, debitar recursos reservados, liberar uma reserva). | Quando um evento do ciclo de vida do pagamento gera um lançamento no ledger. | Costuma vir junto com `RESERVE`, `DEBIT` ou `RELEASE`, mas também pode aparecer com `CREDIT`, conforme o fluxo. | | `BANK` | Criada por um aporte ou movimentação bancária que afeta o saldo do seu ledger pré-financiado. | Quando os recursos se movem entre os rails bancários e o ledger pré-financiado. | Use o valor, a operação, os timestamps e os seus campos de referência externa para conciliar com os registros do lado do banco. | | `POSTED_PAYMENT` | Criada quando um pagamento é formalmente lançado/registrado no ledger como parte do processamento do pagamento. | Quando o sistema registra no ledger um evento de pagamento “lançado”. | Isto diz respeito à origem do lançamento (etapa de lançamento), não necessariamente ao status final do pagamento. | | `CREDIT_MEMO` | Criada por um evento de nota de crédito (por exemplo, um crédito aplicado ao seu ledger fora do fluxo normal de pagamento). | Correções, ajustes ou créditos representados como notas de crédito. | Importante para conciliação e notas contábeis. | | `MANUAL` | Criada manualmente (por exemplo, por uma ação administrativa da API). | Casos excepcionais: correções operacionais ou ações de suporte. | Se você vir `MANUAL` e precisar de detalhes, entre em contato com o Ripple Technical Services informando o `txnReference` e os timestamps. | Origem da transação O `txnSource` informa **qual sistema ou processo criou o lançamento no ledger**. Por si só, ele não indica se houve entrada ou saída de recursos. Isso é indicado pela operação (`CREDIT`/`DEBIT`/`RESERVE`/`RELEASE`) e pelo valor. ## Exemplo de requisição Para solicitar um arquivo **CSV**, você precisa informar o cabeçalho `Accept: text/csv`. Se esse cabeçalho for omitido, a API retorna **JSON** por padrão. **Solicitando CSV (recomendado para conciliação)** ```bash curl -X GET "https://api.test.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" ``` **Solicitando JSON (padrão)** ```bash curl -X GET "https://api.test.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" ``` ## Exemplo de resposta **Resposta em CSV** ```csv tenant,amount,currency,txnReference,operation,txnSource,status,createdDttm,updatedDttm,availableBalanceBefore,availableBalanceAfter rpd2demo,2.06,USD,429161bb-6a71-4bb9-927d-12ae18199ddd,DEBIT,PAYMENTS,SUCCESS,2025-12-12T23:08:23.399345535Z,2025-12-12T23:08:23.399345704Z,1140833.98234594,1140833.98234594 rpd2demo,30,USD,7a3e8c12-4b5f-4d6e-9a1b-8c2d3e4f5a6b,DEBIT,PAYMENTS,SUCCESS,2025-12-12T23:08:01.260806899Z,2025-12-12T23:08:01.260807099Z,1140833.98234594,1140833.98234594 rpd2demo,30,USD,8b4f9d23-5c6e-4f7d-0b2c-9d3e4f5a6b7c,DEBIT,PAYMENTS,SUCCESS,2025-12-12T23:06:59.979143148Z,2025-12-12T23:06:59.979143319Z,1140833.98234594,1140833.98234594 rpd2demo,30,USD,7a3e8c12-4b5f-4d6e-9a1b-8c2d3e4f5a6b,RESERVE,PAYMENTS,SUCCESS,2025-12-12T23:06:34.692569101Z,2025-12-12T23:06:34.692569611Z,1140863.98234594,1140833.98234594 ``` **Resposta em JSON** ```json { "offset": "0", "pageSize": "10", "pageElements": "10", "total": "10000", "statementTransactions": [ { "tenant": "rpd2demo", "amount": "2.06", "currency": "USD", "txnReference": "429161bb-6a71-4bb9-927d-12ae18199ddd", "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", "txnReference": "7a3e8c12-4b5f-4d6e-9a1b-8c2d3e4f5a6b", "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", "txnReference": "8b4f9d23-5c6e-4f7d-0b2c-9d3e4f5a6b7c", "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", "txnReference": "7a3e8c12-4b5f-4d6e-9a1b-8c2d3e4f5a6b", "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", "txnReference": "8b4f9d23-5c6e-4f7d-0b2c-9d3e4f5a6b7c", "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", "txnReference": "429161bb-6a71-4bb9-927d-12ae18199ddd", "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", "txnReference": "9c5a0d34-6e7f-4a8b-9c6a-4b5c6d7e8f9a", "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", "txnReference": "0d6b1e45-7f8a-4b9c-8a7b-5c6d7e8f9a0b", "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", "txnReference": "1e7c2f56-8a9b-4c0d-9b8c-6d7e8f9a0b1c", "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", "txnReference": "1e7c2f56-8a9b-4c0d-9b8c-6d7e8f9a0b1c", "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" } ] } ```