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

# Cobranças

> Como emitir uma cobrança Pix, o que cada campo exige, os status possíveis e o que o pagador recebe.

Esta página é para quem vai emitir cobranças — pelo painel ou por `POST /pix`. O passo a
passo mínimo está no [Quickstart](/quickstart); aqui estão as regras que valem sempre.

## Os dois modos de emitir

**Manual**: você manda valor, descrição e os dados do pagador.

**Por produto**: você manda `product_id` e o servidor calcula tudo — o valor é o preço do
produto (com `coupon_code` opcional, mesmas regras do checkout), a descrição padrão é o
nome do produto e a validade padrão é 24 h. O pagador vem de `customer_id` (cliente já
cadastrado) ou dos campos inline; com `novo_cliente: true`, ele também entra no seu
cadastro de clientes. `success_url` e `cancel_url` (http ou https) definem para onde o
checkout leva o pagador depois.

## Campos e regras

| Regra                                                        | Detalhe                                                                                                                                                                 |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount` em **reais**, decimal                               | `100` é R$ 100,00; `49.9` é R$ 49,90                                                                                                                                    |
| Valor mínimo **R\$ 5,00**                                    | abaixo disso, `400` com `codigo: VALOR_MINIMO` — vale igual em teste e produção                                                                                         |
| `customer_cpf` aceita **CPF ou CNPJ**                        | os dígitos verificadores são conferidos; documento inválido é `400` na hora. Pode vir formatado ou só dígitos                                                           |
| `expires_at` obrigatório no modo manual, e sempre **futuro** | data no passado é `400` com `codigo: EXPIRACAO_INVALIDA` (tolerância de 1 minuto para diferença de relógio); no modo produto o padrão é 24 h                            |
| `expires_at` sempre **com fuso** (`Z` ou `-03:00`)           | data sem fuso é lida no relógio do servidor — **UTC em produção**: quem manda `23:59:00` querendo horário de Brasília cria uma cobrança que expira 3 h antes, sem aviso |
| Obrigatórios no modo manual                                  | `amount`, `description`, `customer_name`, `customer_email`, `customer_cpf`, `expires_at`                                                                                |

A resposta `201` traz a cobrança inteira: `txid` (o identificador que você vai usar em
tudo), `pix_code` (copia e cola), `qr_code_url` (imagem em base64, gerada na hora a
partir do código) e `status: "pending"`.

## Status e ciclo de vida

| Status     | Como chega nele                                    |
| ---------- | -------------------------------------------------- |
| `pending`  | acabou de ser emitida                              |
| `paid`     | o pagamento foi confirmado (ou simulado, em teste) |
| `canceled` | cancelada por você                                 |
| `refunded` | devolvida                                          |

Uma cobrança `pending` que passou do `expires_at` aparece como **expirada** no checkout
e não pode mais ser paga por ali — no banco ela continua `pending`, então filtre por
`expires_at` ao reconciliar.

<Warning>
  `POST /pix/cancel` e `POST /pix/refund` existem, mas **ainda não executam** o
  cancelamento nem a devolução na origem — respondem `502` explicando. Está dito na página
  de cada rota.
</Warning>

## Como saber que foi paga

* **Webhook** (recomendado): o evento `charge.paid` chega no seu endpoint com `txid`,
  `paid_at` e `end_to_end_id`. Veja [Webhooks](/webhooks).
* **Consulta**: `GET /pix/status?txid=…` a qualquer momento.

## O que o pagador recebe

* **Checkout**: toda cobrança tem uma página pública em
  `https://pay.v4companyamaral.com/checkout/{txid}` (é a `checkout_url` do evento
  `charge.created`) — QR code, copia e cola e a confirmação sozinha quando o Pix cai.
* **Comprovante**: paga, a cobrança ganha um comprovante público em
  `https://pay.v4companyamaral.com/comprovante/{txid}`, com o documento do pagador
  mascarado.
* **E-mail**: quando o servidor tem e-mail configurado, o pagador recebe o link do
  comprovante automaticamente na confirmação. Cobrança de teste não gera e-mail.

## Emissão bloqueada?

`409` com `codigo: PRODUCAO_NAO_LIBERADA` significa que a conta ainda não passou pela
[aprovação de produção](/aprovacao-de-producao). No modo subconta também existem
`SUBCONTA_INEXISTENTE` e `SUBCONTA_NAO_APROVADA` — veja
[Erros e códigos](/erros-e-codigos).