Obter saldos e transações do ledger

Neste tutorial, você usará duas operações da API de ledger para monitorar o saldo da sua conta e obter um registro detalhado da atividade na sua conta pré-financiada:

Get available balances — recupera os saldos disponível e reservado atuais da sua conta.
Get ledger transactions — recupera uma lista paginada de transações do ledger dentro de um intervalo de data e hora para conciliação.

Você também aprenderá a:

Paginar grandes conjuntos de resultados usando paginação por offset.
Filtrar por ID de pagamento para localizar todos os lançamentos de ledger associados a um pagamento específico.
Exportar resultados em CSV para usar em fluxos de conciliação.

Para entender como as operações de ledger (RESERVE, DEBIT, CREDIT, RELEASE) afetam o seu saldo, consulte Transações do ledger.

Antes de começar

Para seguir este tutorial, você precisa de:

Acesso ao ambiente UAT da API do Payments Direct.
Um token de acesso OAuth2 válido. Consulte Solicitar um token de acesso.
Pelo menos um pagamento concluído ou em andamento (para observar lançamentos de ledger relevantes).

Etapa 1: Obter os saldos disponíveis

Use a operação Get available balances para ver quanto está disponível no momento na sua conta pré-financiada e quanto está reservado para pagamentos em andamento.

Endpoint

GET /v2/balances

Parâmetro de consulta opcional

Parâmetro	Tipo	Descrição
`currency`	string	Filtra os resultados por uma única moeda (por exemplo, `USD`). Se omitido, todas as moedas são retornadas.

Exemplo de requisição — todas as moedas

curl -X GET "https://api.test.ripple.com/v2/balances" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Exemplo de requisição — apenas USD

curl -X GET "https://api.test.ripple.com/v2/balances?currency=USD" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Exemplo de resposta

{
  "timestamp": "2025-03-15T10:30:00.000000Z",
  "balances": [
    {
      "fundingType": "FUNDED",
      "currency": "USD",
      "availableBalance": "50000.00",
      "reservedBalance": "2500.00"
    }
  ]
}

Entendendo os campos de saldo

Campo	Descrição
`availableBalance`	Recursos que podem ser usados no momento. Este é o saldo que você pode usar para iniciar novos pagamentos.
`reservedBalance`	Recursos atualmente separados para pagamentos em andamento. Você não pode usar este saldo para iniciar novos pagamentos até que a reserva seja liberada ou consumida.
`timestamp`	O momento em que o instantâneo do saldo foi capturado.

Saldo e criação de pagamentos

Se uma requisição de criação de pagamento falhar com o erro USR_067 (Insufficient balance), compare availableBalance com o valor do pagamento. O saldo reservado não está disponível para novos pagamentos.

Etapa 2: Obter as transações do ledger

Use a operação Get ledger transactions para recuperar uma lista paginada de lançamentos de ledger dentro de um intervalo de data e hora. Cada lançamento mostra a operação realizada, o efeito dela sobre o seu saldo disponível e a origem que a criou.

Endpoint

GET /v2/ledger-transactions

Parâmetros de consulta obrigatórios

Parâmetro	Descrição	Exemplo
`currency`	Código de moeda ISO 4217.	`USD`
`start-dttm`	Início do intervalo de data e hora (inclusivo, UTC).	`2025-03-15T00:00:00Z`
`end-dttm`	Fim do intervalo de data e hora (exclusivo, UTC).	`2025-03-16T00:00:00Z`
`page-size`	Número de registros por página. Mínimo: 1, máximo: 50.	`25`

Parâmetros de consulta opcionais

Parâmetro	Descrição	Exemplo
`status`	Filtra os resultados pelo status da transação de ledger. `SUCCESS` retorna as transações de ledger concluídas. `PENDING` está reservado para uso futuro e no momento não retorna resultados.	`SUCCESS`

Outros parâmetros opcionais são abordados mais adiante neste tutorial: offset na Etapa 3, txnReference na Etapa 4, e sort-key e sort-direction em Ordenação dos resultados.

Exemplo de requisição

curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\
currency=USD\
&start-dttm=2025-03-15T00:00:00Z\
&end-dttm=2025-03-16T00:00:00Z\
&page-size=25" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

Exemplo de resposta

{
  "offset": "0",
  "pageSize": "25",
  "pageElements": "4",
  "total": "4",
  "statementTransactions": [
    {
      "tenant": "acme-corp",
      "amount": "14.00",
      "currency": "USD",
      "txnReference": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "operation": "DEBIT",
      "txnSource": "PAYMENTS",
      "status": "SUCCESS",
      "createdDttm": "2025-03-15T10:25:12.000000Z",
      "updatedDttm": "2025-03-15T10:25:12.000000Z",
      "availableBalanceBefore": "49986.00",
      "availableBalanceAfter": "49986.00"
    },
    {
      "tenant": "acme-corp",
      "amount": "14.00",
      "currency": "USD",
      "txnReference": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "operation": "RESERVE",
      "txnSource": "PAYMENTS",
      "status": "SUCCESS",
      "createdDttm": "2025-03-15T10:25:11.000000Z",
      "updatedDttm": "2025-03-15T10:25:11.000000Z",
      "availableBalanceBefore": "50000.00",
      "availableBalanceAfter": "49986.00"
    },
    {
      "tenant": "acme-corp",
      "amount": "10014.00",
      "currency": "USD",
      "txnReference": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "operation": "DEBIT",
      "txnSource": "PAYMENTS",
      "status": "SUCCESS",
      "createdDttm": "2025-03-15T10:25:10.000000Z",
      "updatedDttm": "2025-03-15T10:25:10.000000Z",
      "availableBalanceBefore": "50000.00",
      "availableBalanceAfter": "50000.00"
    },
    {
      "tenant": "acme-corp",
      "amount": "10014.00",
      "currency": "USD",
      "txnReference": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "operation": "RESERVE",
      "txnSource": "PAYMENTS",
      "status": "SUCCESS",
      "createdDttm": "2025-03-15T10:23:45.000000Z",
      "updatedDttm": "2025-03-15T10:23:45.000000Z",
      "availableBalanceBefore": "60014.00",
      "availableBalanceAfter": "50000.00"
    }
  ]
}

Entendendo as operações de ledger

O campo operation informa qual ação foi aplicada à sua conta. A sequência RESERVE → DEBIT é o padrão típico de um pagamento concluído.

Operação	Efeito sobre `availableBalance`	Quando ocorre
`CREDIT`	Aumenta	Recursos são adicionados à sua conta (por exemplo, uma recarga).
`RESERVE`	Diminui	Recursos são separados quando um pagamento entra no estado de validação ou de transferência.
`DEBIT`	Sem alteração (normalmente)	Os recursos reservados são consumidos quando um pagamento é concluído. O saldo disponível já havia diminuído no momento do RESERVE.
`RELEASE`	Aumenta	Os recursos reservados são devolvidos quando um pagamento falha ou é cancelado.
`VOID_BALANCE`	Depende da implementação	Correção administrativa. Entre em contato com o suporte técnico da Ripple para mais detalhes.
`OVERRIDE_BALANCE`	Depende da implementação	Correção administrativa. Entre em contato com o suporte técnico da Ripple para mais detalhes.

Por que o DEBIT não altera o saldo disponível

Quando um pagamento começa, a operação RESERVE tira recursos do saldo disponível e os coloca em estado reservado. Quando o pagamento é concluído, o DEBIT finaliza a saída a partir do valor reservado. Mas, como o saldo disponível já havia diminuído no momento do RESERVE, availableBalanceBefore e availableBalanceAfter normalmente são iguais em um lançamento de DEBIT. Se um pagamento falhar, um lançamento de RELEASE devolve os recursos reservados ao saldo disponível.

Etapa 3: Paginar os resultados

Se o valor de total na resposta for maior que pageElements, há mais registros a recuperar. Use o parâmetro offset para buscar as páginas seguintes.

Padrão: defina offset como um múltiplo de page-size para avançar pelas páginas.

Exemplo: buscar a segunda página

curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\
currency=USD\
&start-dttm=2025-03-15T00:00:00Z\
&end-dttm=2025-03-16T00:00:00Z\
&page-size=25\
&offset=25" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Continue somando page-size ao offset até que pageElements na resposta seja menor que page-size, o que indica que você chegou à última página.

Fixe o intervalo de tempo antes de paginar

Não altere start-dttm nem end-dttm entre páginas da mesma consulta. Alterar o intervalo de tempo no meio da paginação pode fazer você perder ou duplicar registros.

Etapa 4: Filtrar por ID de pagamento

Para localizar todos os lançamentos de ledger associados a um pagamento específico, use o parâmetro txnReference. Para pagamentos, o valor de txnReference é o paymentId retornado quando o pagamento foi criado.

Isso é útil para auditar o impacto de um pagamento específico no saldo (os lançamentos de RESERVE, DEBIT e eventuais RELEASE daquele pagamento).

Exemplo: consultar os lançamentos de ledger de um pagamento específico

curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\
currency=USD\
&start-dttm=2025-03-15T00:00:00Z\
&end-dttm=2025-03-16T00:00:00Z\
&page-size=25\
&txnReference=7ea3399c-1234-5678-8d8f-d320ea406630" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Exemplo de resposta

{
  "offset": "0",
  "pageSize": "25",
  "pageElements": "2",
  "total": "2",
  "statementTransactions": [
    {
      "tenant": "acme-corp",
      "amount": "10014.00",
      "currency": "USD",
      "txnReference": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "operation": "DEBIT",
      "txnSource": "PAYMENTS",
      "status": "SUCCESS",
      "createdDttm": "2025-03-15T10:25:10.000000Z",
      "updatedDttm": "2025-03-15T10:25:10.000000Z",
      "availableBalanceBefore": "50000.00",
      "availableBalanceAfter": "50000.00"
    },
    {
      "tenant": "acme-corp",
      "amount": "10014.00",
      "currency": "USD",
      "txnReference": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "operation": "RESERVE",
      "txnSource": "PAYMENTS",
      "status": "SUCCESS",
      "createdDttm": "2025-03-15T10:23:45.000000Z",
      "updatedDttm": "2025-03-15T10:23:45.000000Z",
      "availableBalanceBefore": "60014.00",
      "availableBalanceAfter": "50000.00"
    }
  ]
}

Isso mostra o impacto completo do pagamento no ledger: os recursos foram reservados quando o pagamento foi criado e debitados quando ele foi concluído.

Etapa 5: Exportar em CSV

Em fluxos de conciliação, você pode solicitar a resposta como arquivo CSV definindo o cabeçalho Accept: text/csv. Se esse cabeçalho for omitido, a API retorna JSON por padrão.

Exemplo: baixar um extrato em CSV

curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\
currency=USD\
&start-dttm=2025-03-01T00:00:00Z\
&end-dttm=2025-04-01T00:00:00Z\
&page-size=50" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: text/csv" \
  -o ledger-march-2025.csv

Formato CSV

A resposta em CSV inclui os mesmos campos da resposta em JSON, como cabeçalhos de coluna:

tenant,amount,currency,txnReference,operation,txnSource,status,createdDttm,updatedDttm,availableBalanceBefore,availableBalanceAfter
acme-corp,10014.00,USD,7ea3399c-1234-5678-8d8f-d320ea406630,DEBIT,PAYMENTS,SUCCESS,2025-03-15T10:25:10Z,2025-03-15T10:25:10Z,50000.00,50000.00
acme-corp,10014.00,USD,7ea3399c-1234-5678-8d8f-d320ea406630,RESERVE,PAYMENTS,SUCCESS,2025-03-15T10:23:45Z,2025-03-15T10:23:45Z,60014.00,50000.00

A paginação também vale para o CSV

As respostas em CSV também são paginadas. Em intervalos de datas grandes, use o parâmetro offset para recuperar as páginas seguintes e concatenar os resultados, omitindo a linha de cabeçalho em todas as páginas depois da primeira.

Ordenação dos resultados

Use sort-key e sort-direction para controlar a ordem dos resultados. Se esses parâmetros forem omitidos, a ordenação padrão é determinada pela API.

curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\
currency=USD\
&start-dttm=2025-03-15T00:00:00Z\
&end-dttm=2025-03-16T00:00:00Z\
&page-size=25\
&sort-key=CREATED_AT\
&sort-direction=DESC" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Valores de sort-key compatíveis:

Valor	Ordena por
`CREATED_AT`	Timestamp de criação da transação
`STATEMENT_OPERATION`	Tipo de operação (CREDIT, DEBIT etc.)
`STATEMENT_SOURCE`	Origem da transação (PAYMENTS, BANK etc.)
`STATEMENT_STATUS`	Status da transação de ledger
`STATEMENT_TXN_REFERENCE`	Referência da transação
`STATEMENT_UPDATED_AT`	Timestamp da última atualização

Tratamento de erros

Código de erro	Status	Descrição	Ação
`USR_251`	400	Parâmetro de requisição ausente.	Falta um parâmetro obrigatório (`currency`, `start-dttm`, `end-dttm` ou `page-size`). Adicione o parâmetro ausente e tente novamente.
`SYS_301`	500	Erro interno do servidor.	Tente novamente com espera exponencial. Entre em contato com o suporte técnico da Ripple se o problema persistir.
`CFG_201`	500	Configuração inválida.	Não foi possível recuperar os saldos por um problema de configuração. Entre em contato com o suporte técnico da Ripple.
`AUTH_001`	401	Não autorizado.	O seu token é inválido ou expirou. Gere um novo token de acesso e tente novamente.

Resumo e próximos passos

Neste tutorial, você:

Recuperou os seus saldos disponível e reservado atuais usando GET /v2/balances.
Buscou uma lista paginada de transações de ledger em um intervalo de datas usando GET /v2/ledger-transactions.
Filtrou as transações por ID de pagamento usando o parâmetro txnReference.
Exportou os resultados em CSV para conciliação.

Próximos passos:

Para entender como as operações de ledger se relacionam com os eventos do ciclo de vida do pagamento, consulte Transações do ledger.
Para criar pagamentos que aparecerão como lançamentos de ledger, consulte Criar um pagamento.
Para ver os códigos de erro relacionados a saldo, consulte Erros da API.
Para monitorar as mudanças de estado do pagamento que geram atividade no ledger, consulte Polling ou Webhooks de notificação.

Obter saldos e transações do ledger

Antes de começar

Etapa 1: Obter os saldos disponíveis

Endpoint

Parâmetro de consulta opcional

Exemplo de requisição — todas as moedas

Exemplo de requisição — apenas USD

Exemplo de resposta

Entendendo os campos de saldo

Etapa 2: Obter as transações do ledger

Endpoint

Parâmetros de consulta obrigatórios

Parâmetros de consulta opcionais

Exemplo de requisição

Exemplo de resposta

Entendendo as operações de ledger

Etapa 3: Paginar os resultados

Exemplo: buscar a segunda página

Etapa 4: Filtrar por ID de pagamento

Exemplo: consultar os lançamentos de ledger de um pagamento específico

Exemplo de resposta

Etapa 5: Exportar em CSV

Exemplo: baixar um extrato em CSV

Formato CSV

Ordenação dos resultados

Tratamento de erros

Resumo e próximos passos

Was this page helpful?