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

# Cobranças Pix

> Criação, estados, valores e idempotência das cobranças.

## Valores e dados

O campo `amountCents` é um inteiro em centavos. Cobranças aceitam de **R$ 2,00** a **R$ 2.000,00**. `payerName` deve ter de 2 a 100 caracteres; `description` pode ter até 200 caracteres e pode ser uma string vazia.

## Idempotência

Cada criação exige `requestKey`, um UUID gerado pela sua aplicação. Repetir a mesma requisição com o mesmo UUID retorna a mesma operação. Reutilizar o UUID com outro valor ou outros dados gera erro. Isso evita cobrar duas vezes após timeout ou perda de resposta.

## Estados

| Status | Significado |
| - | - |
| `unknown` | A Master ainda não confirmou a resposta do provedor. Consulte o mesmo ID. |
| `pending` | Pix gerado e aguardando pagamento. |
| `paid` | Pagamento confirmado. |
| `expired` | Cobrança expirada. |
| `failed` | O provedor recusou ou não conseguiu criar a cobrança. |

Uma resposta `pending` pode conter `copyPaste` e `qrCodeBase64` (data URL PNG). Esses campos são opcionais: use a operação retornada e consulte novamente quando necessário. `paymentMethod` é `pix`; `expiresAt` informa a expiração quando retornada pela liquidante e é `null` quando ela não fornece esse prazo. `paidAt` e `endToEnd` podem aparecer após a liquidação. A Master não inventa uma data de expiração.

## Consultas

`GET /payments/{id}` busca uma operação da sua conta. `GET /payments` retorna até 100 operações recentes. O [webhook](/webhooks) é a primeira fonte de atualização. Após 5 segundos sem atualização, a Master agenda `GET /payments/{paymentId}` autenticado na Z.PAY. O processo funciona mesmo sem consultas do seu aplicativo; erros usam espera crescente e consultas têm limite compartilhado. `GET /payments/{id}` retorna o último estado conciliado e também tenta atualizar quando a consulta está vencida. Consultar o status não confirma manualmente a cobrança e não exige código de e-mail. Nunca marque um pedido como pago apenas porque o Pix foi gerado.

Todas essas rotas utilizam o negócio indicado por `X-Master-Operation`, ou a principal quando omitido. O pagamento retorna `operationId`; mantenha o mesmo header na criação e nas consultas. Não reutilize um `requestKey` em outro negócio.


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