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. O motivo vem em failure_code. | Veja por que falhou. |
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. |
Por que falhou
Quando o status é failed, o campo failure_code diz o motivo. Ele vem na consulta, na lista e no webhook payment.failed.
failure_code | O que significa | O que fazer |
|---|---|---|
payer_document_invalid | O CPF/CNPJ do pagador não foi aceito. | Confira o documento e o nome do pagador e crie outro pagamento. |
payer_data_invalid | Algum dado do pagador não foi aceito. | Confira os dados do pagador e crie outro pagamento. |
charge_refused | A cobrança não pôde ser gerada agora. | Crie outro pagamento. Se continuar, fale com o suporte e informe o id do pagamento. |
Para tentar de novo, crie outro pagamento com uma nova Idempotency-Key e um novo external_id. Repetir a mesma Idempotency-Key não cria outra cobrança: devolve a resposta da primeira chamada.
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.