Refunds

Refund objects allow you to refund a previously created charge that isn’t refunded yet. Funds are refunded to the credit or debit card that’s initially charged.

Related guide: Refunds

Was this section helpful? Yes No

Create a refund

POST / v1 / refunds

Update a refund

POST / v1 / refunds /:id

Retrieve a refund

GET / v1 / refunds /:id

List all refunds

GET / v1 / refunds

Cancel a refund

POST / v1 / refunds /:id / cancel

The Refund object

Attributes

id string Unique identifier for the object.
amount integer Amount, in the smallest currency unit.
charge nullable string Expandable ID of the charge that’s refunded.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
description nullable string An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
payment _ intent nullable string Expandable ID of the PaymentIntent that’s refunded.
reason nullable enum Reason for the refund, which is either user-provided ( duplicate, fraudulent, or requested_by_customer) or generated by Stripe internally ( expired_uncaptured_charge).
status nullable string Status of the refund. This can be pending, requires_action, succeeded, failed, or canceled. Learn more about failed refunds.

More attributes

object string, value is "refund"
balance _ transaction nullable string Expandable
created timestamp
customer nullable string Expandable
customer _ account nullable string
destination _ details nullable object
failure _ balance _ transaction nullable string Expandable
failure _ reason nullable string
instructions _ email nullable string
next _ action nullable object
payment _ method nullable string Expandable
pending _ reason nullable enum
presentment _ details nullable object
receipt _ number nullable string
source _ transfer _ reversal nullable string Expandable Connect only
transfer _ reversal nullable string Expandable Connect only

The Refund object

{ "id": "re_1Nispe2eZvKYlo2Cd31jOCgZ", "object": "refund", "amount": 1000, "balance_transaction": "txn_1Nispe2eZvKYlo2CYezqFhEx", "charge": "ch_1NirD82eZvKYlo2CIvbtLWuY", "created": 1692942318, "currency": "usd", "destination_details": { "card": { "reference": "123456789012", "reference_status": "available", "reference_type": "acquirer_reference_number", "type": "refund" }, "type": "card" }, "metadata": {}, "payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp", "reason": null, "receipt_number": null, "source_transfer_reversal": null, "status": "succeeded", "transfer_reversal": null}

Create a refund

POST / v1 / refunds

When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create it.

Creating a new refund will refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged.

You can optionally refund only part of a charge. You can do so multiple times, until the entire charge has been refunded.

Once entirely refunded, a charge can’t be refunded again. This method will raise an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.

Parameters

amount integer A positive integer in the smallest currency unit representing how much of this charge to refund. Can refund only up to the remaining, unrefunded amount of the charge.
charge string The identifier of the charge to refund.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
payment _ intent string The identifier of the PaymentIntent to refund.
reason string String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. If you believe the charge to be fraudulent, specifying fraudulent as the reason will add the associated card and email to your block lists, and will also help us improve our fraud detection algorithms.

More parameters

instructions _ email string
origin enum
refund _ application _ fee boolean Connect only
reverse _ transfer boolean Connect only

Returns

Returns the Refund object if the refund succeeded. Raises an error if the Charge/PaymentIntent has already been refunded, or if an invalid identifier was provided.

Response

{ "id": "re_1Nispe2eZvKYlo2Cd31jOCgZ", "object": "refund", "amount": 1000, "balance_transaction": "txn_1Nispe2eZvKYlo2CYezqFhEx", "charge": "ch_1NirD82eZvKYlo2CIvbtLWuY", "created": 1692942318, "currency": "usd", "destination_details": { "card": { "reference": "123456789012", "reference_status": "available", "reference_type": "acquirer_reference_number", "type": "refund" }, "type": "card" }, "metadata": {}, "payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp", "reason": null, "receipt_number": null, "source_transfer_reversal": null, "status": "succeeded", "transfer_reversal": null}