A valid request URL is required to generate request examples{
"id": "<string>",
"object": "refund",
"livemode": true,
"charge_id": "<string>",
"payment_intent_id": "<string>",
"terminal_id": "<string>",
"amount": 123,
"currency": "<string>",
"status": "pending",
"reason": "requested_by_customer",
"settlement_batch_id": "<string>",
"settled_at": 123,
"failure_message": "<string>",
"created_at": 123,
"updated_at": 123
}{
"error": {
"code": "INVALID_REQUEST",
"message": "invalid currency"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
},
"refund": {
"id": "<string>",
"object": "refund",
"livemode": true,
"charge_id": "<string>",
"payment_intent_id": "<string>",
"terminal_id": "<string>",
"amount": 123,
"currency": "<string>",
"status": "pending",
"reason": "requested_by_customer",
"settlement_batch_id": "<string>",
"settled_at": 123,
"failure_message": "<string>",
"created_at": 123,
"updated_at": 123
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "CHARGE_NOT_FOUND",
"message": "charge not found"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "GATEWAY_ERROR",
"message": "refund was not sent to the payment processor and no money moved; retry with a new Idempotency-Key"
}
}Create a refund
Refunds a charge. Identify it with exactly one of charge_id or
payment_intent_id. Omit amount for a full refund, or pass an amount
in minor units for a partial one. For a settled PIN-debit terminal
payment, pass the Ionic terminal_id assigned to your account where the customer
will present the card. When Ionic has turned on refunds on the Terminal for
your account, a full refund with terminal_id before the batch settles voids
the sale on the Terminal that took it, with no card, and the Terminal prints
the receipt; naming another Terminal returns 422. When automatic refund
receipts are on for your account, a card-present refund with terminal_id
prints its receipt on that Terminal; a refund without it prints only through
POST /terminals/{id}/print. Ionic chooses Void,
Refund, or interactive Return; never send a device serial number or credential. A refund settles
asynchronously; its status is pending until the result is final.
A valid request URL is required to generate request examples{
"id": "<string>",
"object": "refund",
"livemode": true,
"charge_id": "<string>",
"payment_intent_id": "<string>",
"terminal_id": "<string>",
"amount": 123,
"currency": "<string>",
"status": "pending",
"reason": "requested_by_customer",
"settlement_batch_id": "<string>",
"settled_at": 123,
"failure_message": "<string>",
"created_at": 123,
"updated_at": 123
}{
"error": {
"code": "INVALID_REQUEST",
"message": "invalid currency"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
},
"refund": {
"id": "<string>",
"object": "refund",
"livemode": true,
"charge_id": "<string>",
"payment_intent_id": "<string>",
"terminal_id": "<string>",
"amount": 123,
"currency": "<string>",
"status": "pending",
"reason": "requested_by_customer",
"settlement_batch_id": "<string>",
"settled_at": 123,
"failure_message": "<string>",
"created_at": 123,
"updated_at": 123
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "CHARGE_NOT_FOUND",
"message": "charge not found"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "GATEWAY_ERROR",
"message": "refund was not sent to the payment processor and no money moved; retry with a new Idempotency-Key"
}
}Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.
^mer_[0-9A-Za-z]{14}$Body
Identify the charge with exactly one of charge_id or payment_intent_id.
The charge to refund (ch_…).
The intent whose latest charge to refund (pi_…).
Amount in minor units. Omit for a full refund.
Optional terminal (tmr_…) used when a card-present Refund requires an interactive card or PIN prompt, or, when refunds on the Terminal are on for your account, the Terminal that took the sale, which voids a same-day full refund and prints its receipt. With automatic refund receipts on, a card-present refund's receipt prints on this Terminal.
An optional audit/reporting category: one of requested_by_customer, duplicate, or fraudulent. Omitted values record no reason and have no effect on refund behavior.
requested_by_customer, duplicate, fraudulent Response
The created refund.
A return of some or all of a charge's funds to the customer.
The refund id (rf_…).
Always refund.
refund Mirrors the mode of the underlying charge.
The refunded charge (ch_…).
The parent payment intent (pi_…).
Terminal (tmr_…) selected for the Refund request, or null when no terminal was supplied.
The refunded amount, in minor units. Full or partial.
The refund's currency, matching amount's currency.
pending while the Refund is being processed; uncertain when its final outcome is not known yet. Retrieve the Refund again before retrying.
pending, succeeded, failed, uncertain An optional audit/reporting category: one of requested_by_customer, duplicate, or fraudulent. Null when not supplied; has no effect on refund behavior.
requested_by_customer, duplicate, fraudulent Terminal batch (tmb_…) containing this Refund. Null until the Refund is settled in a batch.
Unix epoch seconds when the Refund settled. Null until settlement completes.
A human-readable failure detail. Nullable; present when the refund failed.
Unix epoch seconds when the refund was created.
Unix epoch seconds when the refund was last updated.