Error

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>"
  }
}

Payments

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. 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.

POST

refunds

Error

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>"
  }
}

Authorizations

Authorization

string

header

required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json

Identify the charge with exactly one of charge_id or payment_intent_id.

charge_id

string

The charge to refund (ch_…).

payment_intent_id

string

The intent whose latest charge to refund (pi_…).

amount

integer | null

Amount in minor units. Omit for a full refund.

terminal_id

string

Optional terminal (tmr_…) used when a card-present Refund requires an interactive card or PIN prompt.

reason

enum<string>

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.

Available options:

requested_by_customer,

duplicate,

fraudulent

Response

The created refund.

string

required

The refund id (rf_…).

object

enum<string>

required

Always refund.

Available options:

refund

livemode

boolean

required

Mirrors the mode of the underlying charge.

charge_id

string

required

The refunded charge (ch_…).

payment_intent_id

string

required

The parent payment intent (pi_…).

terminal_id

string | null

required

Terminal (tmr_…) selected for the Refund request, or null when no terminal was supplied.

amount

integer

required

The refunded amount, in minor units. Full or partial.

currency

string

required

The refund's currency, matching amount's currency.

status

enum<string>

required

pending while the Refund is being processed; uncertain when its final outcome is not known yet. Retrieve the Refund again before retrying.

Available options:

pending,

succeeded,

failed,

uncertain

reason

enum<string> | null

required

An optional audit/reporting category — one of requested_by_customer, duplicate, or fraudulent. Null when not supplied; has no effect on refund behavior.

Available options:

requested_by_customer,

duplicate,

fraudulent

settlement_batch_id

string | null

required

Terminal batch (tmb_…) containing this Refund. Null until the Refund is settled in a batch.

settled_at

integer | null

required

Unix epoch seconds when the Refund settled. Null until settlement completes.

failure_message

string | null

required

A human-readable failure detail. Nullable; present when the refund failed.

created_at

integer

required

Unix epoch seconds when the refund was created.

updated_at

integer

required

Unix epoch seconds when the refund was last updated.

Start here

Checkout

Commerce

Checkout endpoints

Payment link endpoints

Catalog endpoints

Payments

Terminal locations

Terminal management

Terminal testing

Terminal payments

Invoices

Subscriptions

Setup intents

Credit notes

Webhook endpoints

Customer endpoints

API key endpoints

Payment method endpoints

Create a refund

Authorizations

Headers

Body

Response