> ## 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 | no modo produto o padrão é 24 h                                                                               |
| 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).