Charges
post/v1/charges/{charge}/refunds

Create customer balance refund

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.

Path parameters

NameDescription
charge*The identifier of the charge to refund.

Request body

FieldTypeDescription
amountinteger
currencystring (currency)

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customerstring

Customer whose customer balance to refund from.

expandarray<string>

Specifies which fields in the response should be expanded.

instructions_emailstring

For payment methods without native refund support (e.g., Konbini, PromptPay), use this email from the customer to receive refund instructions.

metadataobject | string

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.

originstring

Origin of the refund

payment_intentstring

The identifier of the PaymentIntent to refund.

reasonstring

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.

refund_application_feeboolean

Boolean indicating whether the application fee should be refunded when refunding this charge. If a full charge refund is given, the full application fee will be refunded. Otherwise, the application fee will be refunded in an amount proportional to the amount of the charge refunded. An application fee can be refunded only by the application that created the charge.

reverse_transferboolean

Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed proportionally to the amount being refunded (either the entire or partial amount).<br><br>A transfer can be reversed only by the application that created the charge.

Response

FieldTypeDescription
amount*integer

Amount, in cents (or local equivalent).

balance_transactionstring | balance_transaction

Balance transaction that describes the impact on your account balance.

chargestring | charge

ID of the charge that's refunded.

created*integer (unix-time)

Time at which the object was created. Measured in seconds since the Unix epoch.

currency*string (currency)

Three-letter ISO currency code, in lowercase. Must be a supported currency.

descriptionstring

An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).

destination_detailsrefund_destination_details
30 nested fields
FieldTypeDescription
affirmdestination_details_unimplemented
afterpay_clearpaydestination_details_unimplemented
alipaydestination_details_unimplemented
almadestination_details_unimplemented
amazon_paydestination_details_unimplemented
au_bank_transferdestination_details_unimplemented
blikrefund_destination_details_blik
br_bank_transferrefund_destination_details_br_bank_transfer
cardrefund_destination_details_card
cashappdestination_details_unimplemented
cryptorefund_destination_details_crypto
customer_cash_balancedestination_details_unimplemented
epsdestination_details_unimplemented
eu_bank_transferrefund_destination_details_eu_bank_transfer
gb_bank_transferrefund_destination_details_gb_bank_transfer
giropaydestination_details_unimplemented
grabpaydestination_details_unimplemented
jp_bank_transferrefund_destination_details_jp_bank_transfer
klarnadestination_details_unimplemented
mb_wayrefund_destination_details_mb_way
multibancorefund_destination_details_multibanco
mx_bank_transferrefund_destination_details_mx_bank_transfer
nz_bank_transferdestination_details_unimplemented
p24refund_destination_details_p24
paynowdestination_details_unimplemented
paypalrefund_destination_details_paypal
pixdestination_details_unimplemented
revolutdestination_details_unimplemented
scalapaydestination_details_unimplemented
sofortdestination_details_unimplemented
failure_balance_transactionstring | balance_transaction

After the refund fails, this balance transaction describes the adjustment made on your account balance that reverses the initial balance transaction.

failure_reasonstring

Provides the reason for the refund failure. Possible values are: lost_or_stolen_card, expired_or_canceled_card, charge_for_pending_refund_disputed, insufficient_funds, declined, merchant_request, or unknown.

id*string

Unique identifier for the object.

instructions_emailstring

For payment methods without native refund support (for example, Konbini, PromptPay), provide an email address for the customer to receive refund instructions.

metadataobject

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.

next_actionrefund_next_action
2 nested fields
FieldTypeDescription
display_detailsrefund_next_action_display_details
type*string

Type of the next action to perform.

object*string

String representing the object's type. Objects of the same type share the same value.

payment_intentstring | payment_intent

ID of the PaymentIntent that's refunded.

pending_reasonstring

Provides the reason for why the refund is pending. Possible values are: processing, insufficient_funds, or charge_pending.

presentment_detailspayment_flows_payment_intent_presentment_details
2 nested fields
FieldTypeDescription
presentment_amount*integer

Amount intended to be collected by this payment, denominated in presentment_currency.

presentment_currency*string

Currency presented to the customer during payment.

reasonstring

Reason for the refund, which is either user-provided (duplicate, fraudulent, or requested_by_customer) or generated by Stripe internally (expired_uncaptured_charge).

receipt_numberstring

This is the transaction number that appears on email receipts sent for this refund.

source_transfer_reversalstring | transfer_reversal

The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account.

statusstring

Status of the refund. This can be pending, requires_action, succeeded, failed, or canceled. Learn more about failed refunds.

transfer_reversalstring | transfer_reversal

This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter.