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

  1. Crie o pagamento e guarde o id junto com o pedido.
  2. Espere o webhook. Quando chegar payment.paid, valide a assinatura e libere o pedido.
  3. Como reforço, consulte GET /v1/payments/{id} enquanto o status for pending. Consulte no máximo uma vez a cada 30 segundos por pagamento.
  4. Pare de consultar quando o status for final: paid, expired, failed, canceled ou refunded.

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

StatusO que significaO que fazer
pendingCriado. Esperando o cliente pagar.Mostre o Pix e espere.
paidPago e confirmado. O valor entrou no seu saldo.Libere o pedido. É final.
expiredO prazo (expires_at) acabou sem pagamento.Não mostre mais o Pix. Crie outro pagamento se o cliente ainda quiser pagar.
failedNão foi possível criar a cobrança Pix. O motivo vem em failure_code.Veja por que falhou.
canceledA cobrança foi cancelada antes do pagamento.Não libere. Crie outro pagamento se precisar.
refundedO 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_codeO que significaO que fazer
payer_document_invalidO CPF/CNPJ do pagador não foi aceito.Confira o documento e o nome do pagador e crie outro pagamento.
payer_data_invalidAlgum dado do pagador não foi aceito.Confira os dados do pagador e crie outro pagamento.
charge_refusedA 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

  1. O cliente fecha o pedido 1234 no seu site.
  2. Seu servidor calcula o total (R$ 150,00) e chama POST /v1/payments com amount_cents: 15000 e Idempotency-Key: pedido-1234.
  3. Seu servidor guarda o id devolvido no pedido 1234 e mostra o pix.copy_paste ao cliente.
  4. O cliente paga. Você recebe o webhook payment.paid, valida a assinatura, confere que o id é o do pedido 1234 e libera.
  5. Se o webhook não chegar em alguns minutos, a consulta de reforço encontra paid e você libera do mesmo jeito.
  6. Se nada acontecer até expires_at, o status vira expired e 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.