Skip to content

Refunds

HTTP
POST /v1/payments/{paymentId}/refunds
Idempotency-Key: refund-1042-1
{ "amount": 2500, "reason": "Damaged item" }
  • Only a succeeded payment can be refunded, through the processor that captured it.
  • The amount (minor units) is checked under a lock against what is still refundable: the captured amount minus succeeded, pending and unknown refunds (pending and unknown count as spent). Errors: 422 refund_exceeds_refundable (with refundable), 422 refund_currency_mismatch, 422 refund_non_positive, 422 invalid_request ("Only captured payments can be refunded").
  • GET /v1/payments/{id}/refundable tells you the remaining amount first.
  • A refund starts pending; the processor's webhook or a status fetch makes it succeeded or failed. unknown means the processor did not answer; GIEP reconciles it and it counts as spent meanwhile. Listen for refund.succeeded / refund.failed.
  • POST /v1/refunds/bulk takes up to 100 items, each with its own key, and reports a result per item.