Pagamentos
Consultar o status da forma correta
Use o webhook como fonte principal e a consulta por id como reforço, com intervalo mínimo. Veja cada status e o que fazer.
Faça assim
- Crie o pagamento e guarde o
idjunto com o pedido. - Espere o webhook. Quando chegar
payment.paid, valide a assinatura e libere o pedido. - Como reforço, consulte
GET /v1/payments/{id}enquanto o status forpending. Consulte no máximo uma vez a cada 30 segundos por pagamento. - Pare de consultar quando o status for final:
paid,expired,failed,canceledourefunded.
Por que o webhook primeiro
O webhook chega segundos depois do pagamento. A consulta repetida gasta o seu limite de requisições e atrasa a confirmação. Use a consulta só para cobrir um webhook perdido, por exemplo se o seu servidor estava fora do ar.
Status do pagamento
| Status | O que significa | O que fazer |
|---|---|---|
pending | Criado. Esperando o cliente pagar. | Mostre o Pix e espere. |
paid | Pago e confirmado. O valor entrou no seu saldo. | Libere o pedido. É final. |
expired | O prazo (expires_at) acabou sem pagamento. | Não mostre mais o Pix. Crie outro pagamento se o cliente ainda quiser pagar. |
failed | Não foi possível criar a cobrança Pix. | Crie outro pagamento com um novo external_id. |
canceled | A cobrança foi cancelada antes do pagamento. | Não libere. Crie outro pagamento se precisar. |
refunded | O valor foi devolvido ao cliente. | Desfaça a liberação do pedido. É final. |
Exemplo de fluxo completo
- O cliente fecha o pedido 1234 no seu site.
- Seu servidor calcula o total (R$ 150,00) e chama
POST /v1/paymentscomamount_cents: 15000eIdempotency-Key: pedido-1234. - Seu servidor guarda o
iddevolvido no pedido 1234 e mostra opix.copy_pasteao cliente. - O cliente paga. Você recebe o webhook
payment.paid, valida a assinatura, confere que oidé o do pedido 1234 e libera. - Se o webhook não chegar em alguns minutos, a consulta de reforço encontra
paide você libera do mesmo jeito. - Se nada acontecer até
expires_at, o status viraexpirede você encerra o pedido.
Erros ao consultar
Se a consulta falhar com 429 ou 5xx, espere e tente de novo, aumentando a espera a cada tentativa. Não aumente a frequência das consultas.