Refund a Charge
Refund a succeeded card charge in full
Behavior
- The request takes no body — the full charge amount is always refunded.
- On success the charge transitions to the terminal
refundedstatus and the response is the same charge object returned by Retrieve a Charge, withstatus: "refunded". - A charge can only be refunded once; a second attempt fails because the charge is no longer in the
succeededstatus. - If you subscribe to the opt-in
checkout.refundedwebhook, it fires when the charge transitions.
Settlement timing
Card transactions settle in a daily batch, typically the next business day. The processor cannot refund a transaction before it settles — a same-day refund attempt fails with a 422 whoseresponsetext carries the processor’s decline reason. Retry after the settlement batch.
Authorizations
Bearer token authentication using your API key (key_...). Used for every endpoint except POST /api/v1/device_pings.
Path Parameters
Unique identifier of the charge to refund.
"ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK"
Response
The refund succeeded. Returns the charge in the same shape as GET /api/v1/charges/{id}, with status "refunded".
"ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK"
Charge amount in cents.
2999
Direction of the charge: credit for deposits (money into the customer balance), debit for withdrawals (money out).
credit, debit "debit"
"USD"
Current state of the charge. Not every value is reachable on every flow or processor: held occurs on withdrawals that place a hold; voided and returned follow a settled charge that the processor later reversed; cancelled applies to bank-transfer payments cancelled while still pending; refunded is set by a full refund of a settled NMI card charge via POST /api/v1/charges/{id}/refund or the dashboard, and emits the opt-in checkout.refunded event. cancelled emits no webhook. See the charge lifecycle for the full transition map and which webhook each transition emits.
created, pending, succeeded, failed, held, voided, returned, refunded, cancelled "succeeded"
Machine-readable failure code; only present when status is failed.
null
Human-readable failure reason; only present when status is failed.
null
"2026-05-31T10:30:00.000Z"
"2026-05-31T10:30:05.000Z"
Payment method used for the charge. Exactly one of card, bank_account, or crypto_wallet is populated, matching payment_type.
Address Verification System result from the processor. Card charges only.
null
CVV verification result from the processor. Card charges only.
null
Authorization code returned by the card network. Card charges only.
null
External processor's identifier for this charge. Card charges only.
null
3D Secure verification details. Only present for card charges where 3DS was performed.

