> ## 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.

# Cobranças Pix

> Emita cobranças Pix, acompanhe status e consulte o copia e cola sem precisar configurar webhook.

Emita cobranças Pix diretamente para uma carteira da sua conta, receba o copia e cola e o QR code, e acompanhe a situacao pela API. Nao e necessario configurar webhook: a consulta sincroniza o estado com a provedora.

> [!NOTE]
>
> Requer escopo `payments:create` para criar e `payments:read` para consultar.

## Requisitos

Antes de criar uma cobranca, confirme que:

* A conta esta ativa e habilitada financeiramente.
* O servidor esta com `PAYMENTS_ENABLED=true`.
* A carteira informada pertence a propria conta.
* O valor esta dentro do limite por pagamento da conta (consulte `/v1/account/fees-limits`).
* A provedora esta configurada.

Novos cadastros sao ativados para recebimento apos confirmacao de e-mail. KYC e obrigatorio apenas para saques.

## Criar cobranca

Envie `POST /v1/payments` com `Idempotency-Key` obrigatorio no header. O corpo exige `amountCents`, `walletId` e `description`.

**amountCents** `integer` *required*

Valor em centavos de BRL. Minimo 1. Exemplo: `1000` para R\$ 10,00.

**walletId** `string` *required*

UUID da carteira da conta.

**description** `string` *required*

Descricao da cobranca (1 a 300 caracteres).

**externalReference** `string`

Referencia do pedido no seu sistema (ate 100 caracteres).

```bash curl theme={"theme":"github-dark-default"}
  curl -X POST https://api.bunnipay.com.br/v1/payments \
    -H "Content-Type: application/json" \
    -H "X-API-Key: SUA_CHAVE" \
    -H "Idempotency-Key: pedido-123-unico" \
    -d '{
      "amountCents": 1000,
      "walletId": "550e8400-e29b-41d4-a716-446655440000",
      "description": "Pedido #123",
      "externalReference": "PEDIDO-123"
    }'
```

**data.id** `string` *required*

UUID da cobranca criada.

**data.amountCents** `integer` *required*

Valor em centavos.

**data.status** `string` *required*

Situacao inicial: `pending`.

**data.copyPaste** `string`

Copia e cola do Pix. Pode ser nulo.

**data.qrSvg** `string`

QR code em SVG. Nulo quando indisponivel.

**data.expiresAt** `string`

Data/hora de expiracao no formato ISO 8601.

## Status de uma cobranca

Uma cobranca pode estar em uma das seguintes situacoes:

| Status | Significado |
| - | - |
| `pending` | Aguardando pagamento. |
| `paid` | Pagamento confirmado. |
| `expired` | Prazo de pagamento esgotado. |
| `refunded` | Valor estornado. |
| `unknown` | Situacao nao determinada; consulte novamente. |

## Expiracao

Novas cobrancas tem prazo maximo de **1 hora** desde a intencao persistida. O prazo pode ser menor se a provedora indicar outro valor. Apos expirar, o copia e cola deixa de ser retornado. Confirmacoes tardias da provedora ainda podem ser conciliadas uma vez.

## Consultar cobranca

Use `GET /v1/payments/{id}` para sincronizar a situacao com a provedora. A rota consulta a provedora diretamente, mesmo sem webhook configurado.

```bash curl theme={"theme":"github-dark-default"}
curl https://api.bunnipay.com.br/v1/payments/550e8400-e29b-41d4-a716-446655440001 \
  -H "X-API-Key: SUA_CHAVE"
```

## Consultar Pix (copia e cola)

Use `GET /v1/payments/{id}/pix` para obter o copia e cola original e sincronizar a situacao.

```bash curl theme={"theme":"github-dark-default"}
curl https://api.bunnipay.com.br/v1/payments/550e8400-e29b-41d4-a716-446655440001/pix \
  -H "X-API-Key: SUA_CHAVE"
```

> [!WARNING]
>
> `pending`, `processing` e `unknown` nao confirmam entrega de dinheiro. Somente `paid` confirma o recebimento.

## Tarifas

As tarifas de recebimento dependem da operacao da conta:

* **White (Wyze):** fixa de 40 centavos.
* **Black (Kyvo):** 399 pontos-base (3,99%) mais 70 centavos.

Consulte `/v1/account/fees-limits` para os valores exatos da sua conta.

## Idempotencia

Sempre envie `Idempotency-Key` ao criar. Se houver falha de comunicacao, repita a requisicao com a **mesma chave, mesmo corpo e mesma credencial**. Nao crie outra chave para tentar resolver um resultado incerto. Conflitos retornam HTTP 409.

## Erros comuns

| HTTP | Codigo / causa | Acao recomendada |
| - | - | - |
| 400 | Campos, parametros ou headers invalidos | Revise o corpo e os headers. |
| 401 | Chave ausente, invalida ou revogada | Verifique `X-API-Key`. |
| 403 | Conta sem habilitacao financeira | Complete a habilitacao da conta. |
| 409 | Conflito de idempotencia | Aguarde e consulte o pagamento pelo ID. |
| 422 | Valor fora do limite ou abaixo da tarifa | Ajuste `amountCents`. |
| 429 | Limite de requisicoes excedido | Aguarde o intervalo de `Retry-After`. |
| 502 | Provedora indisponivel ou resultado incerto | Mantenha a intencao e consulte pelo ID. |
| 503 | `PAYMENTS_NOT_ENABLED` ou infraestrutura | Entre em contato com o suporte. |


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