> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar cobranças

> Lista as cobranças da sua conta em páginas, da mais recente para a mais antiga, com filtros por status, moeda, período e busca por texto.

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

| Situação | Como usar esta rota |
| - | - |
| Tela de vendas no seu sistema | Liste sem filtros: a ordem é sempre da mais recente para a mais antiga |
| Conciliação do dia | `status=paid` com `createdAtStart` e `createdAtEnd` no mesmo dia, percorrendo as páginas |
| Acompanhar contestações | `status=pre_chargeback`, `status=chargeback` ou `status=blocked` |
| Achar a cobrança depois de um timeout na criação | `createdAtStart` + `createdAtEnd` do dia e `searchFor` com o documento ou o e-mail do comprador |
| Saber o status atual de **uma** cobrança | Use [`GET /v1/charges/{id}`](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar), que é mais direto |

> [!NOTE]
>
> 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](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#idempotência).

## Antes de chamar

* Tenha uma chave secreta (`sk_` ou `sk_test_`) ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* 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.

**page** `integer` (default: 1)

Número da página. Começa em `1`.

**size** `integer` (default: 10)

Quantidade de cobranças por página. Ex.: `50`.

**status** `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`.

**currency** `string`

Filtra pela moeda, no padrão ISO 4217. Ex.: `BRL`.

**createdAtStart** `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`.

**createdAtEnd** `string`

Data final do período, no formato `AAAA-MM-DD`. Envie **junto com** `createdAtStart`. Ex.: `2026-10-27`.

**merchantId** `string`

Filtra pelo ID da conta dona da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**searchFor** `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`.

> [!WARNING]
>
> 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

| Status | Significado |
| - | - |
| `pending` | Aguardando pagamento (ex.: Pix gerado e ainda não pago) |
| `paid` | Pago com sucesso |
| `refused` | Recusado (emissor, antifraude ou 3DS obrigatório) |
| `failed` | Falha no processamento |
| `refunded` | Estornado |
| `in_analysis` | Em análise antifraude |
| `authentication_required` | Aguardando autenticação do comprador |
| `pre_chargeback` | Alerta de pré-chargeback recebido antes de o chargeback ser formalizado |
| `chargeback` | Chargeback formalizado |

A explicação completa de cada status e das transições está em [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md).

### 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](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md). 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.

**data** `object[]`

Cobranças da página atual, da mais recente para a mais antiga.

**propriedades da cobrança**

**id** `string`

Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**status** `string`

Status da cobrança (tabela acima).

**chargebackAlertRefunded** `boolean | null`

Em cobranças com alerta de pré-chargeback: `true` se o valor já foi estornado ao comprador, `false` se a disputa está aberta sem estorno. `null` quando não há alerta.

**chargebackAlertReason** `string | null`

Motivo ou referência informado no alerta de pré-chargeback. Ex.: `Chargeback - NSU 123456789`.

**pspRefId** `string | null`

Identificador da cobrança no provedor de pagamento (PSP). Ex.: `ch_123456789`.

**amount** `number`

Valor total da cobrança, em reais. Ex.: `100.5`.

**currency** `string`

Moeda no padrão ISO 4217. Ex.: `BRL`.

**spread** `number`

Spread (taxa) aplicado à cobrança. Ex.: `2.5`.

**net** `number`

Valor líquido depois do spread. Ex.: `98`.

**customer** `object`

Cliente: `id`, `name`, `email` e `document` (texto).

**paymentMethod** `object`

Forma de pagamento. No Pix, `type` `pix`. No cartão: `type`, `firstSix`, `lastFour`, `expirationMonth`, `expirationYear`, `holderName` e `installments`.

**merchantId** `string`

Identificador da conta dona da cobrança.

**paymentDetails** `object | null`

Detalhes do pagamento. No cartão: `firstSix`, `lastFour`, `expirationMonth`, `expirationYear`, `holderName`, `installments` e, no Apple Pay, `brand`. No Pix: `endToEndId`, `copyPaste`, `qrCodeBase64` e, opcionalmente, `expiresAt`.

**metadata** `object | null`

Informações livres enviadas na criação, com as chaves em **camelCase**: chaves enviadas em snake\_case chegam convertidas. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata).

**paidAt** `string | null`

Data e hora do pagamento, em ISO 8601.

**createdAt** `string`

Data e hora da criação, em ISO 8601.

**updatedAt** `string`

Data e hora da última atualização, em ISO 8601.

**page** `integer`

Número da página atual. Ex.: `1`.

**pages** `integer`

Total de páginas disponíveis. Ex.: `10`.

**total** `integer`

Total de cobranças somando todas as páginas. Ex.: `100`.

**size** `integer`

Quantidade de cobranças por página. Ex.: `10`.

> [!NOTE]
>
> 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](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md).

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista obtida | `data`, `page`, `pages`, `total`, `size` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Perfil do usuário dono da chave sem permissão | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` |

> [!NOTE]
>
> **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`:

```javascript theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

async function listarDoDia(dia, status) {
  const todas = [];
  let page = 1;
  let pages = 1;
  do {
    const params = new URLSearchParams({
      status,
      createdAtStart: dia,
      createdAtEnd: dia,
      page: String(page),
      size: '50',
    });
    const res = await fetch(`https://api-global.fastpaybrasil.com/v1/charges?${params}`, {
      headers: { Authorization: `Basic ${credentials}` },
    });
    const body = await res.json();
    todas.push(...body.data);
    pages = body.pages;
    page += 1;
  } while (page <= pages);
  return todas;
}

const pagas = await listarDoDia('2026-10-27', 'paid');
```

> [!TIP]
>
> **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

> [tab] Vendas recentes
>
> As 20 cobranças mais novas, para uma tela de acompanhamento.
>
> ```bash theme={null}
> curl "https://api-global.fastpaybrasil.com/v1/charges?page=1&size=20" \
>   -u "$FINVIA_API_KEY:"
> ```

> [tab] Depois de um timeout
>
> Cobranças criadas hoje para o comprador de CPF `52998224725`. Compare `metadata.orderId` e `amount` com o pedido que deu timeout.
>
> ```bash theme={null}
> curl "https://api-global.fastpaybrasil.com/v1/charges?createdAtStart=2026-10-27&createdAtEnd=2026-10-27&searchFor=52998224725&size=50" \
>   -u "$FINVIA_API_KEY:"
> ```

> [tab] Cobranças bloqueadas
>
> Cobranças com bloqueio por MED ou chargeback, para a equipe de atendimento acompanhar.
>
> ```bash theme={null}
> curl "https://api-global.fastpaybrasil.com/v1/charges?status=blocked" \
>   -u "$FINVIA_API_KEY:"
> ```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` em toda chamada | Cabeçalho ausente, chave inválida ou Base64 sem os dois pontos no final | Decodifique o Base64 e confira se termina em `:` |
| Lista vazia com vendas existentes | Chave de teste consultando vendas de produção, ou o contrário | Use a chave do mesmo ambiente em que as cobranças foram criadas |
| Filtro de data não se comporta como esperado | Só um dos parâmetros `createdAtStart` e `createdAtEnd` foi enviado, ou a data veio em outro formato | Envie os dois juntos, no formato `AAAA-MM-DD` |
| Ordenação ou tamanho ignorados | `orderBy` e `limit` não existem nesta rota | A ordem é fixa (mais recente primeiro). Para o tamanho, use `size` |
| Uma tentativa recusada não aparece | Tentativas agrupadas aparecem só em `groupCharges` da principal | Consulte a cobrança principal |
| `metadata.order_id` não encontrado | Chaves enviadas em snake\_case vêm em camelCase | Leia `metadata.orderId` ou envie as chaves em camelCase. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata) |

```http REST (JSON) theme={null}
GET /v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20 HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const params = new URLSearchParams({
  status: 'paid',
  createdAtStart: '2026-10-27',
  createdAtEnd: '2026-10-27',
  page: '1',
  size: '20',
});

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/charges?${params}`, {
  headers: { Authorization: `Basic ${credentials}` },
});

const { data, page, pages, total } = await response.json();
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "2vorkDcXyvzifL63YX09S9VqcnI",
      "status": "paid",
      "chargebackAlertRefunded": null,
      "chargebackAlertReason": null,
      "pspRefId": "ch_123456789",
      "amount": 100.5,
      "currency": "BRL",
      "spread": 2.5,
      "net": 98,
      "customer": {
        "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
        "name": "Maria Souza",
        "email": "maria@email.com",
        "document": "529.982.247-25"
      },
      "paymentMethod": {
        "type": "credit_card",
        "firstSix": "444433",
        "lastFour": "1111",
        "expirationMonth": "10",
        "expirationYear": "2028",
        "holderName": "MARIA SOUZA",
        "installments": 3
      },
      "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH",
      "paymentDetails": {
        "firstSix": "444433",
        "lastFour": "1111",
        "expirationMonth": "10",
        "expirationYear": "2028",
        "holderName": "MARIA SOUZA",
        "installments": 3
      },
      "metadata": { "orderId": "ORD-3091" },
      "paidAt": "2026-10-27T14:30:00Z",
      "createdAt": "2026-10-27T14:30:00Z",
      "updatedAt": "2026-10-27T14:30:00Z"
    }
  ],
  "page": 1,
  "pages": 10,
  "total": 100,
  "size": 10
}
```

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

```json 403 theme={null}
{
  "statusCode": 403,
  "message": "Acesso negado",
  "error": "Forbidden"
}
```

## Veja também

> [card] [Consultar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md)
>
> Status, bloqueio, split e tentativas agrupadas de uma cobrança.

> [card] [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
>
> O que significa cada status e quando ele muda.

> [card] [Paginação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)
>
> Regras de `page` e `size` e o procedimento para timeout.

> [card] [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
>
> Como tratar contestações e bloqueios.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.