Estornos
Peça a devolução integral de uma cobrança paga e acompanhe o resultado assíncrono pelo refundId.
/api/v1/paymentintents/{id}/refund-requestsO mesmo endpoint estorna Pix, cartão e Pix parcelado. O estorno é integral e assíncrono: a resposta 202 diz que o pedido foi aceito, não que o dinheiro já voltou.
Solicite
curl -X POST "$DM_API_BASE/api/v1/paymentintents/$PAYMENT_INTENT_ID/refund-requests" \
-H "Authorization: $DM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Cancelamento solicitado pelo comprador",
"idempotencyKey": "estorno-pedido-1001-tentativa-1"
}'{
"refundId": "rfnd_EXEMPLO",
"status": "requested"
}| Campo | Descrição |
|---|---|
reason | Motivo, para seu registro e rastreabilidade. Opcional. |
idempotencyKey | Chave da tentativa de estorno, no corpo. Opcional, recomendada. O cabeçalho Idempotency-Key da criação de cobrança não substitui esse campo. |
Os dois campos são opcionais: envie {} para um pedido sem motivo e sem chave. Não envie amount: o estorno é sempre do valor total. Trate refundId como identificador opaco.
Respostas
| Situação | Resultado |
|---|---|
Cobrança Succeeded | 202. Grave o refundId. |
| Estorno já em andamento | 202 com o mesmo refundId, mesmo que você envie outra chave. |
| Estorno já concluído | 409 AlreadyRefunded. Nenhuma devolução nova é iniciada. |
| Cobrança ainda não paga | 422 PaymentIntentNotRefundable. |
| Cobrança inexistente | 404 PaymentIntentNotFound. |
Acompanhe
| Resposta ou evento | Como tratar |
|---|---|
requested | Pedido recebido. Aguarde o resultado. |
processing | Devolução em processamento. |
pending_review | Resultado em verificação. Mantenha o estorno pendente. |
payment_intent.refunded | Devolução concluída. Registre com o refundId do evento. |
payment_intent.refund_failed | A tentativa falhou. Registre o motivo e avalie um novo pedido. |
Os estados requested, processing e pending_review aparecem na resposta do pedido ou de uma repetição. A consulta do PaymentIntent não mostra refundStatus nem refundId: quando a devolução conclui, o status da cobrança passa a Refund.
Nova tentativa após falha
Depois de payment_intent.refund_failed, um novo pedido de estorno é permitido. Use uma nova idempotencyKey para a nova tentativa e grave o refundId devolvido. Reserve a mesma chave só para repetir a comunicação da tentativa em curso. Faça o novo pedido de forma deliberada, depois de analisar o motivo.
Correlacione os eventos pela tentativa: uma notificação atrasada com o refundId antigo não deve encerrar nem sobrescrever a tentativa atual.
Quando a resposta demora
Não converta a ausência de webhook em falha e não diga ao comprador que a devolução aconteceu só por causa do 202. Mantenha o estorno em acompanhamento, consulte o pagamento e acione a equipe de integração com o id do PaymentIntent e o refundId quando precisar investigar.
Nunca crie outra cobrança para "compensar" um estorno sem desfecho. O pagamento original e cada tentativa de devolução devem continuar vinculados no seu controle.