Skip to main content
GET
Esta rota devolve as cobranças (charges) da sua conta em páginas. Ela serve para montar telas de acompanhamento, fazer conciliação diária, encontrar cobranças em um status específico (por exemplo, tudo o que está em pre_chargeback ou bloqueado) e localizar uma cobrança depois de um timeout na criação.

Quando usar

Não há filtro por metadata, pelo número do seu pedido nem por valor. Para localizar uma cobrança, combine o período com searchFor e compare metadata e amount do seu lado. O procedimento completo para timeout está em Idempotência.

Antes de chamar

  • Tenha uma chave secreta (sk_ ou sk_test_) (Credenciais e ambientes).
  • A chave de teste lista só as cobranças de teste; a chave de produção lista só as cobranças reais.

Parâmetros de consulta

Nenhum parâmetro é obrigatório. Sem parâmetros, a rota devolve a primeira página com 10 cobranças.
integer
default:"1"
Número da página. Começa em 1.
integer
default:"10"
Quantidade de cobranças por página. Ex.: 50.
string
Filtra pelo status da cobrança: paid, pending, refused, failed, refunded, in_analysis, authentication_required, pre_chargeback ou chargeback. O valor blocked lista as cobranças bloqueadas (MED ou chargeback em análise), que continuam com status paid.
string
Filtra pela moeda, no padrão ISO 4217. Ex.: BRL.
string
Data inicial do período, no formato AAAA-MM-DD, sobre a data de criação. Envie junto com createdAtEnd. O filtro pega o dia inteiro, no fuso do servidor (UTC). Ex.: 2026-10-27.
string
Data final do período, no formato AAAA-MM-DD. Envie junto com createdAtStart. Ex.: 2026-10-27.
string
Filtra pelo ID da conta dona da cobrança. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.
string
Busca parcial, sem diferenciar maiúsculas de minúsculas, em: nome, e-mail, documento e telefone do comprador; seis primeiros e quatro últimos dígitos do cartão; título do primeiro item; pspRefId; endToEndId do Pix; e nome da conta. Ex.: 52998224725.
A API ignora parâmetros desconhecidos sem dar erro. orderBy, limit ou metadata na URL não filtram nem ordenam nada, e a lista volta como se eles não existissem. Use só os parâmetros desta página.

O que significa cada status

A explicação completa de cada status e das transições está em Status de cobrança.

Tentativas agrupadas

No cartão, tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas. A listagem mostra só a cobrança principal do grupo. As demais tentativas aparecem em groupCharges, na consulta da cobrança principal. Leve isso em conta ao contar tentativas recusadas ou ao procurar uma cobrança específica.

Respostas

A resposta 200 traz a página pedida (data) e os totais para você navegar pelas demais páginas.
object[]
Cobranças da página atual, da mais recente para a mais antiga.
integer
Número da página atual. Ex.: 1.
integer
Total de páginas disponíveis. Ex.: 10.
integer
Total de cobranças somando todas as páginas. Ex.: 100.
integer
Quantidade de cobranças por página. Ex.: 10.
A lista de splits e as tentativas agrupadas (groupCharges) não vêm na listagem. Para ver a divisão do valor ou o bloqueio (isBlocked, blockedAt, blockedReason) de uma cobrança, use a consulta individual.
Para o negócio: amount é o valor total da cobrança e net é o valor líquido depois do spread. Para acompanhar disputas, filtre por blocked (valor retido enquanto a disputa é analisada), pre_chargeback e chargeback.

Percorrer todas as páginas

Para exportar ou conciliar um volume grande, peça páginas até chegar ao valor de pages:
Para o desenvolvedor: se novas cobranças forem criadas enquanto você percorre as páginas, os itens mudam de posição e uma cobrança pode aparecer em duas páginas. Use o id para eliminar repetições e prefira filtrar por um período já encerrado.

Exemplos por caso de uso

As 20 cobranças mais novas, para uma tela de acompanhamento.

Erros comuns

Veja também

Consultar cobrança

Status, bloqueio, split e tentativas agrupadas de uma cobrança.

Status de cobrança

O que significa cada status e quando ele muda.

Paginação e idempotência

Regras de page e size e o procedimento para timeout.

Bloqueio, chargeback e MED

Como tratar contestações e bloqueios.