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

# Listar Cobranças

> Retorna as cobranças da empresa com filtros e paginação

## Descrição

Retorna uma lista paginada das cobranças da empresa, criadas pela API e pelo Dashboard, com filtros por status, método e data. Os depósitos feitos na própria conta não entram na lista.

***

## Headers

**Authorization** `string` *required* (default: Bearer YOUR\_API\_KEY)

Bearer token de autenticação. Formato: `Bearer YOUR_API_KEY`

***

## Query Parameters

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

Quantidade de resultados (mín: 1, máx: 100)

**starting\_after** `string`

Cursor de paginação: ID da última cobrança da página anterior

**method** `string`

Filtrar por método de pagamento: `pix`

**status** `string`

Filtrar por status: `creating`, `pending`, `paid`, `expired`, `failed`, `review`

**created\[gte]** `string`

Data mínima de criação (ISO 8601)

**created\[lte]** `string`

Data máxima de criação (ISO 8601)

***

## Exemplo de Requisição

```bash cURL theme={null}
# Listar as últimas 20 cobranças pagas
curl "https://api.visepag.com/v1/payins?limit=20&method=pix&status=paid" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash Paginação theme={null}
# Próxima página após o último ID retornado
curl "https://api.visepag.com/v1/payins?limit=10&starting_after=54e2b712-aca0-4230-b69a-d6dd8542c925" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript Node.js theme={null}
const params = new URLSearchParams({
  limit: '20',
  method: 'pix',
  status: 'paid',
  'created[gte]': '2026-03-01T00:00:00Z',
  'created[lte]': '2026-03-31T23:59:59Z'
});

const response = await fetch(
  `https://api.visepag.com/v1/payins?${params}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const { data, has_more } = await response.json();
```

***

## Resposta `200 OK`

**object** `string`

Sempre `"list"`

**data** `array`

Lista de cobranças, no mesmo formato da [consulta](https://docs.visepag.com/api-reference/payins/get-payin.md)

**has\_more** `boolean`

`true` se existem mais resultados

**url** `string`

URL do endpoint

```json 200 theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "54e2b712-aca0-4230-b69a-d6dd8542c925",
      "status": "paid",
      "method": "pix",
      "amount": 1000,
      "platformFee": 70,
      "description": "Pedido #1234",
      "customerName": "João Silva",
      "customerDocument": "52998224725",
      "customerEmail": "joao@email.com",
      "pixCopy": "00020101021226...",
      "pixQrCode": null,
      "createdAt": "2026-03-05T18:14:48Z",
      "paidAt": "2026-03-05T18:16:22Z",
      "expiresAt": "2026-03-06T18:14:48Z",
      "currency": "brl",
      "livemode": true
    }
  ],
  "has_more": true,
  "url": "/v1/payins"
}
```

***

## Paginação

A API usa **cursor-based pagination** com o campo `starting_after`:

```javascript theme={null}
// Buscar todas as cobranças automaticamente
async function buscarTodasCobrancas() {
  const cobrancas = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({ limit: '100' });
    if (cursor) params.set('starting_after', cursor);

    const res = await fetch(`https://api.visepag.com/v1/payins?${params}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    const { data, has_more } = await res.json();

    cobrancas.push(...data);
    cursor = has_more ? data[data.length - 1].id : null;
  } while (cursor);

  return cobrancas;
}
```

> [!NOTE]
>
> Quando `has_more` é `true`, existem mais resultados. Use o `id` da última cobrança retornada como `starting_after` para buscar a próxima página.

***

## Erros

| Status | Código | Descrição |
| - | - | - |
| `400` | `invalid_parameter` | `limit`, `status`, `method`, datas ou `starting_after` inválidos |


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