# Cobrar

Há dois caminhos, e o lojista escolhe:

1. **Checkout hospedado** — cria um payment link no painel, copia o endereço e
   entrega. Nós tratamos da página, do cartão e do estado.
2. **Integração por API** — você constrói o checkout e chama-nos. É este guia.

## O pedido

```
POST /api/v1/payments/authorize
Authorization: Bearer sk_...
X-Tenant-Id: <a sua loja>
Idempotency-Key: <um identificador seu, único por tentativa>
```

```json
{
  "amount_minor": 8900,
  "currency": "BRL",
  "payment_method": "pix",
  "external_reference": "PEDIDO-1234",
  "customer": { "name": "...", "email": "...", "tax_id": "..." }
}
```

**O valor vai em unidade menor** — centavos. `8900` são oitenta e nove reais.
Nunca enviamos nem aceitamos decimais nesse campo: arredondamento no meio do
caminho é como um gateway perde cêntimos que somam.

## A chave de idempotência não é opcional na prática

Se a rede falhar depois de nós recebermos e antes de você receber a resposta,
repetir com a **mesma** chave devolve a mesma cobrança em vez de criar outra. Sem
ela, o seu cliente é cobrado duas vezes e quem explica é você.

Use algo que identifique a tentativa do lado de vocês — o id do pedido serve, se
uma nova tentativa de pagamento gerar uma chave nova.

## Os estados

| | |
|---|---|
| `PENDING` | criada, à espera do comprador |
| `PROCESSING` | a falar com o adquirente |
| `AUTHORIZED` | reservado no cartão — **ainda não é dinheiro seu** |
| `PAID` / `CAPTURED` | liquidado |
| `REFUSED` | o emissor recusou |
| `EXPIRED` | o prazo passou sem pagamento |
| `PARTIALLY_REFUNDED` / `REFUNDED` | devolvido, em parte ou no todo |

**Não trate `AUTHORIZED` como venda concluída.** É uma reserva, e pode não vir a
ser capturada.

## Não fique a perguntar

Um Pix não é aprovado na hora: quem paga sai para o banco e volta. Em vez de
consultar em ciclo, **configure um webhook** — avisamos o seu sistema quando o
estado muda. Ver o guia de webhooks.

Se precisar consultar mesmo assim: `GET /api/v1/payments/{id}`.

## Devolver

```
POST /api/v1/payments/{id}/refunds
Idempotency-Key: <obrigatório aqui>
```

Sem `amount_minor`, devolve o que resta. Com ele, devolve essa parte — e pode
repetir até somar o total.

A chave é **obrigatória** no estorno, ao contrário da cobrança. O motivo é
simples: uma cobrança a mais você estorna; um estorno a mais tem de ir pedir o
dinheiro de volta ao comprador.