Skip to main content
POST
Refund a succeeded card charge. The full amount is returned to the customer’s card — partial refunds are not supported. The charge must belong to the merchant whose API key is used; otherwise the API responds with a 422 indistinguishable from “not found”, by design.
Refunds are currently supported for card charges processed via the NMI gateway. Requests for other charges return a 422 with an explanatory error.

Behavior

  • The request takes no body — the full charge amount is always refunded.
  • On success the charge transitions to the terminal refunded status and the response is the same charge object returned by Retrieve a Charge, with status: "refunded".
  • A charge can only be refunded once; a second attempt fails because the charge is no longer in the succeeded status.
  • If you subscribe to the opt-in checkout.refunded webhook, 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 whose responsetext carries the processor’s decline reason. Retry after the settlement batch.

Authorizations

Authorization
string
header
required

Bearer token authentication using your API key (key_...). Used for every endpoint except POST /api/v1/device_pings.

Path Parameters

id
string
required

Unique identifier of the charge to refund.

Example:

"ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK"

Response

The refund succeeded. Returns the charge in the same shape as GET /api/v1/charges/{id}, with status "refunded".

id
string
Example:

"ch_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK"

amount_cents
integer

Charge amount in cents.

Example:

2999

transaction_type
enum<string>

Direction of the charge: credit for deposits (money into the customer balance), debit for withdrawals (money out).

Available options:
credit,
debit
Example:

"debit"

currency
string
Example:

"USD"

status
enum<string>

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.

Available options:
created,
pending,
succeeded,
failed,
held,
voided,
returned,
refunded,
cancelled
Example:

"succeeded"

failure_code
string | null

Machine-readable failure code; only present when status is failed.

Example:

null

failure_message
string | null

Human-readable failure reason; only present when status is failed.

Example:

null

created_at
string<date-time>
Example:

"2026-05-31T10:30:00.000Z"

updated_at
string<date-time>
Example:

"2026-05-31T10:30:05.000Z"

customer
object
payment_method
object

Payment method used for the charge. Exactly one of card, bank_account, or crypto_wallet is populated, matching payment_type.

avs_result
string | null

Address Verification System result from the processor. Card charges only.

Example:

null

cvv_result
string | null

CVV verification result from the processor. Card charges only.

Example:

null

network_authorization_code
string | null

Authorization code returned by the card network. Card charges only.

Example:

null

processor_charge_id
string | null

External processor's identifier for this charge. Card charges only.

Example:

null

threeds
object | null

3D Secure verification details. Only present for card charges where 3DS was performed.