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.io/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,
  "currentStatus": "refunded",
  "refundStatus": "succeeded"
}

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 (ex. Pix pendente), use POST /v1/payments/{paymentId}/cancel.