Consulte um pagamento
Leia o estado atual de um PaymentIntent, interprete cada status e saiba quais campos guardar para conciliação.
/api/v1/paymentintents/{id}A consulta devolve o estado atual da cobrança. É a fonte da verdade quando um webhook atrasa, chega fora de ordem ou não chega.
curl "$DM_API_BASE/api/v1/paymentintents/$PAYMENT_INTENT_ID" \
-H "Authorization: $DM_API_KEY"PAYMENT_INTENT_ID é o id devolvido na criação, o mesmo que aparece em data.id nos webhooks.
Interprete o status
status | Significado | Ação |
|---|---|---|
Created | Recurso criado, sem confirmação de processamento. Não representa pagamento. | Aguarde. |
Processing | Aguardando o comprador pagar ou o processamento terminar. | Aguarde webhook ou consulte de novo. |
RequiresAction | Há um desafio 3DS pendente. Veja nextAction. | Exiba o desafio. |
Succeeded | Pagamento confirmado. | Conclua o pedido. |
Failed | Pagamento não concluído. Veja lastPaymentError. | Oriente o comprador. |
Canceled | Cobrança encerrada ou expirada. | Encerre a oferta, mas aceite confirmação tardia de Pix. |
Refund | Estorno integral concluído. | Registre o estorno. |
ChargedBack | A cobrança de cartão foi contestada e o valor, devolvido ao portador. | Registre a contestação. Veja o evento payment_intent.charged_back. |
Para o ciclo completo, veja O objeto PaymentIntent.
Leituras logo depois de um evento
Logo depois da criação ou de um webhook, a consulta pode devolver um estado anterior ou um 404 temporário. Repita após alguns segundos. Nunca use uma leitura isolada para desfazer uma confirmação já validada: um pedido pago não volta a "aguardando" por causa de uma consulta atrasada.
Campos para guardar
| Campo | Para quê |
|---|---|
id | Vincular a cobrança ao pedido. |
amount, currency | Conferir com o pedido antes de concluir. |
status | Estado atual. |
metadata | As referências que você enviou, como orderId. Não use como prova de vínculo: confira o id. |
created | Momento da criação. |
succeededAt | Momento da confirmação, quando houver. |
Datas são ISO 8601. Guarde o valor original e converta o fuso só para exibição.
Em cartão, a resposta pode trazer paymentMethods[].card.bin, lastFourDigits, cardTokenUid e threeDs. threeDs.used diz se houve autenticação 3DS; threeDs.liabilityShift pode ser true, false ou null enquanto não apurado.
nextAction, lastPaymentError e os blocos do método podem vir null. Campos novos podem ser incluídos: o seu leitor de JSON deve ignorar o que não conhece.
Estornos na consulta
A consulta não tem campo de estado do estorno. Enquanto um estorno estiver pendente ou se ele falhar, a cobrança continua Succeeded. Quando o estorno conclui, o status passa a Refund. Guarde o refundId e acompanhe os webhooks de estorno.