Refunds

A refund returns funds against a payment. Each refund is tied to one payment; an invoice with multiple payments may have multiple refunds.

Object

{
  "id": "ref_…",
  "object": "refund",
  "payment_id": "pay_…",
  "invoice_id": "inv_…",
  "credit_note_id": "cn_…",
  "amount":   "25.00",
  "currency": "USD",
  "destination": "original_method",
  "status": "succeeded",
  "reason": "order_change",
  "provider_id": "re_…",
  "failure_reason": null,
  "metadata": {},
  "created_at": "2026-05-07T10:00:00Z",
  "completed_at": "2026-05-07T10:00:42Z"
}

Status

pending, succeeded, failed, canceled.

Endpoints

Method	Path	What
POST	/v1/payments/{id}/refunds	Create.
GET	/v1/refunds/{id}	Retrieve.
GET	/v1/refunds	List + filter.

Destination

destination	Effect
original_method (default)	Returns funds to the payment method that captured.
wallet	Credits the customer’s wallet in the payment currency.

What happens automatically

A refund creates an accompanying credit note, posts the reversing ledger entries, and adjusts any active recognition schedule for the originating line item. Affiliate commissions attributable to the originating payment are reversed if still within the hold period.

Idempotency

Use a fresh Idempotency-Key per refund attempt. Reusing the original payment’s key has no effect (different route, different intent).

Webhook events

refund.created, refund.succeeded, refund.failed.