Estorno

Devolve ao pagador um valor de um pagamento já aprovado.

Estorno move dinheiro. Repetir a chamada sem a mesma Idempotency-Key pode estornar em dobro. Sempre envie a mesma chave ao tentar de novo.

Estornar um pagamento

curl -X POST https://api.paygrid.tech/v1/payments/{paymentId}/refund \
  -H "X-Api-Key: sk_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: estorno-pedido-4211" \
  -d '{
    "amount": 1990
  }'

Use o paymentId (id público estável do pagamento). Se omitir o amount, estorna o valor total.

Resposta

{
  "paymentId": "pay_01H...",
  "amount": 1990,
  "refundedAmount": 1990,
  "remainingAmount": 0,
  "status": "refunded",
  "refundStatus": "succeeded"
}

Status do estorno

O campo refundStatus diz o que aconteceu com este pedido de estorno:

`refundStatus`	Significado
`succeeded`	O provedor confirmou o estorno.
`pending`	O provedor aceitou e ainda está processando. O `status` do pagamento não muda até a confirmação.
`failed`	O provedor recebeu e recusou. Nada foi estornado.
`failed_before_send`	O pedido nem chegou ao provedor. Nada foi estornado.
`pending_reconciliation`	O pedido pode ter chegado e a resposta se perdeu. Não peça outro estorno até o resultado ser conciliado.

Estorno de Pix pode ser assíncrono. O provedor costuma responder pending e concluir depois. O resultado final chega pelo webhook (payment.refunded, quando o estorno é total) e aparece em GET /v1/payments/{paymentId} (refundedAmount e status). Um estorno pending já conta como comprometido: não dá para pedir de volta mais que o saldo restante enquanto ele não conclui.

Estornos feitos fora do Paygrid

Estornos feitos direto no painel da Pagar.me também chegam ao Paygrid. O estorno total gera payment.refunded; o parcial não gera evento — só atualiza o refundedAmount. Para detectá-lo, consulte GET /v1/payments/{paymentId}.

Regras

Só estorna pagamento aprovado.
Não pode estornar mais do que o valor restante.
Pode estornar parcialmente (amount menor que o total).

Cancelamento

Para cancelar uma cobrança ainda não paga, use POST /v1/payments/{paymentId}/cancel.

Pix pendente não se cancela: o provedor recusa. Ele expira sozinho no fim do prazo e vira cancelled com failureReason: "pix_expirado". Veja Cobrança Pix.