The Refund object

{
  "id": "rf_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "refund",
  "payment_intent_id": "pi_01JEXAMPLE2K8V4N9C6M1Q7R",
  "charge_id": "ch_01JEXAMPLE2K8V4N9C6M1Q7R",
  "amount": 2500,
  "currency": "usd",
  "status": "pending",
  "reason": "requested_by_customer",
  "terminal_id": null,
  "failure_message": null,
  "livemode": false
}

{
  "id": "rf_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "refund",
  "payment_intent_id": "pi_01JEXAMPLE2K8V4N9C6M1Q7R",
  "charge_id": "ch_01JEXAMPLE2K8V4N9C6M1Q7R",
  "amount": 2500,
  "currency": "usd",
  "status": "pending",
  "reason": "requested_by_customer",
  "terminal_id": null,
  "failure_message": null,
  "livemode": false
}

{
  "id": "rf_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "refund",
  "payment_intent_id": "pi_01JEXAMPLE2K8V4N9C6M1Q7R",
  "charge_id": "ch_01JEXAMPLE2K8V4N9C6M1Q7R",
  "amount": 2500,
  "currency": "usd",
  "status": "pending",
  "reason": "requested_by_customer",
  "terminal_id": null,
  "failure_message": null,
  "livemode": false
}

Refunds reverse money that has already been captured through a completed checkout payment. For exact payloads, required fields, examples, and response schemas, open the endpoint pages in this group.

Attributes

string

The refund id (rf_…).

string

The parent payment intent (pi_…).

string

The refunded charge (ch_…).

integer

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

string

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

string

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

string | null

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

string | null

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

string | null

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

See every field in the response of Retrieve a refund.

Endpoints

Endpoint	Use it for
Create refund	Create a full or partial refund for a completed payment.
List refunds	Review refund history or build reporting.
Get refund	Retrieve one refund by `rf_` ID.

Notes

Use the Charge or PaymentIntent ID returned by the completed payment.
Send amount for a partial refund. Omit it for a full refund when supported by the original payment state.
Use metadata to connect refunds to support tickets, return authorizations, or order records.
Use an Idempotency-Key when creating refunds from support tooling or automated workflows.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

Attributes

Endpoints

Notes

​Attributes

​Endpoints

​Notes

Attributes

Endpoints

Notes