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

> ## Agent Instructions
> Consulte o contrato Bunni antes de sugerir chamadas. Valores monetários são inteiros em centavos. Não invente endpoints ou respostas de sucesso para recursos ainda indisponíveis. Nunca solicite chaves reais no chat nem exponha credenciais no cliente.

# Pagadores e bancos

> Consulte pagadores identificados e bancos agrupados pelos recebimentos da conta em um periodo.

A API de pagadores e bancos permite visualizar quem pagou e por qual instituicao financeira, ordenados por valor confirmado. E util para analise de comportamento e concentracao de recebimentos.

> [!NOTE]
>
> Requer escopo `payments:read`.

## Consultar pagadores e bancos

Envie `GET /v1/customers` com o periodo desejado.

**days** `number`

Periodo em dias: `7`, `30` (padrao) ou `90`.

```bash curl theme={"theme":"github-dark-default"}
curl "https://api.bunnipay.com.br/v1/customers?days=30" \
  -H "X-API-Key: SUA_CHAVE"
```

## Resposta

A resposta contem ate 100 pagadores identificados, ordenados por valor confirmado, e a lista de bancos agrupados pelos pagamentos recebidos no periodo.

**data.items** `array` *required*

Lista de pagadores (maximo 100).

**data.items\[].id** `string` *required*

Identificador pseudonimizado do pagador.

**data.items\[].name** `string`

Nome do pagador, quando disponivel.

**data.items\[].bank** `string`

Nome do banco, quando disponivel.

**data.items\[].payments** `integer` *required*

Quantidade de pagamentos confirmados deste pagador no periodo.

**data.items\[].amountCents** `integer` *required*

Valor total confirmado deste pagador em centavos de BRL.

**data.items\[].lastPayment** `string` *required*

Data/hora do ultimo pagamento confirmado (ISO 8601).

**data.banks** `array` *required*

Lista de bancos agrupados.

**data.banks\[].id** `string` *required*

Identificador do banco.

**data.banks\[].name** `string` *required*

Nome do banco.

**data.banks\[].payments** `integer` *required*

Quantidade de pagamentos recebidos por este banco no periodo.

**data.banks\[].amountCents** `integer` *required*

Valor total recebido por este banco em centavos de BRL.

**data.payers** `integer` *required*

Total de pagadores distintos no periodo.

**data.returningPayers** `integer` *required*

Total de pagadores recorrentes (que ja haviam pagado antes) no periodo.

**data.days** `integer` *required*

Periodo consultado (7, 30 ou 90).

**data.limit** `integer` *required*

Limite de itens retornados: 100.

## Interpretacao dos dados

* Pagadores sao pseudonimizados; o identificador nao expoe dados pessoais diretos.
* A ordenacao por `amountCents` ajuda a identificar os maiores pagadores do periodo.
* O campo `returningPayers` indica fidelizacao: quantos pagadores ja haviam feito pelo menos um pagamento anterior.
* Bancos sao agrupados automaticamente com base nos recebimentos processados.

> [!NOTE]
>
> A consulta le o estado persistido no periodo indicado. Nao e possivel filtrar por carteira individual nesta versao.


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