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

# Listar cobranças

> As cobranças da conta, da mais nova para a mais antiga, com filtros e paginação por cursor.

Escopo `payments:list`. Os filtros são aplicados no servidor e valem para a lista inteira, com o cursor (não só para a página). Para saber de um pagamento, prefira o webhook `payment.paid` a listar em laço.

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

De 1 a 100.

**cursor** `string`

O `nextCursor` da página anterior. Inválido: `400 INVALID_CURSOR`.

**status** `string`

Só as cobranças nesta situação: `pending` (aguardando pagamento), `paid` (paga), `expired` (vencida sem pagamento) ou `refunded` (estornada por inteiro). A pendente que já passou do prazo entra em `expired`.

**method** `string`

Só as desta forma de pagamento: `pix`, `card` ou `crypto`.

**customerId** `string`

Só as deste cliente (o `id` de [Listar clientes](https://docs.wyzecash.com.br/referencia/clientes/listar-clientes.md)).

**subaccountId** `string`

Só as desta subconta (o `sacc_...` ou o seu `externalId`), inclusive as divididas com ela.

**q** `string`

Busca, sem diferença de maiúscula ou acento, no código `BKY-`, na descrição, no nome ou CPF/CNPJ mascarado de quem pagou e no nome do cliente. Até 80 caracteres.

## Resposta

**items** `object[]`

Cada item tem o mesmo formato de [Criar cobrança](https://docs.wyzecash.com.br/referencia/cobrancas/criar-cobranca.md): `id`, `status`, `statusTitle`, `amount`, `fee`, `refundedAmount`, `description`, `txid`, `copyPaste`, `expiresAt`, `paidAt`, `customer`, `payer`, `createdAt`.

**nextCursor** `string | null`

Mande em `?cursor=` para a próxima página. `null` quando acabou.

```bash cURL theme={null}
curl "https://api.wyzecash.com.br/v1/payments?limit=20&status=paid&method=pix" \
  -H "Authorization: Bearer bk_live_..."
```

```json 200 theme={null}
{
  "items": [
    {
      "id": "BKY-7KQ2M9XP4RZT",
      "status": "paid",
      "statusTitle": "Pix recebido",
      "amount": 15000,
      "fee": 50,
      "refundedAmount": 0,
      "description": "Pedido 1842",
      "txid": "7kq2m9xp4rzt1a2b3c4d5e6f",
      "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
      "expiresAt": "2026-10-08T15:30:00.000Z",
      "paidAt": "2026-10-08T15:04:11.000Z",
      "customer": null,
      "payer": { "name": "Ana Souza", "document": "***.456.789-**", "institution": "Banco Exemplo" },
      "createdAt": "2026-10-08T15:00:00.000Z"
    }
  ],
  "nextCursor": "WyIyMDI2LTEwLTA4VDE1OjAwOjAwLjAwMFoiLCIuLi4iXQ"
}
```


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