Sample - Stripe API
POST/v1/terminal/readers/{reader}/refund_payment

Refund a Charge or PaymentIntent on a Reader

Triggers an in-person refund on a Reader for a Charge or PaymentIntent. Provide charge or payment_intent and optionally use amount, refund configuration, metadata, or transfer and application-fee options to control the refund. The Reader returns its current state after the refund flow is initiated.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 8 body fields
readerstringrequired
The unique identifier of the Reader on which to initiate the in-person refund. Maximum 5000 characters.

Optional refund details and configuration for initiating an in-person refund on a Reader.

amountintegeroptional
A positive integer in __cents__ representing how much of this charge to refund.
chargestringoptional
ID of the Charge to refund.
expandarray<string>optional
Specifies which fields in the response should be expanded.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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_intentstringoptional
ID of the PaymentIntent to refund.
refund_application_feebooleanoptional
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.
refund_payment_configobjectoptional
Configuration overrides for this refund, such as customer cancellation settings.
reverse_transferbooleanoptional
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). A transfer can be reversed only by the application that created the charge.

2 status codes
200Returns the Reader object, including its identifier, device type, label, software version, network status, and most recent action.
actionobjectoptional
The most recent action performed by the reader.
device_sw_versionstringoptional
The current software version of the reader.
device_typestringrequired
Device type of the reader.
Allowed:bbpos_chipper2xbbpos_wisepad3bbpos_wisepos_emobile_phone_readersimulated_stripe_s700simulated_stripe_s710simulated_verifone_m425simulated_verifone_p630simulated_verifone_ux700simulated_verifone_v660psimulated_wisepos_estripe_m2
idstringrequired
Unique identifier for the object.
ip_addressstringoptional
The local IP address of the reader.
labelstringrequired
Custom label given to the reader for easier identification.
last_seen_atintegeroptional
The last time this reader reported to Stripe backend. Timestamp is measured in milliseconds since the Unix epoch. Unlike most other Stripe timestamp fields which use seconds, this field uses milliseconds.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
locationstringoptional
The location identifier of the reader.
metadataobjectrequired
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:terminal.reader
serial_numberstringrequired
Serial number of the reader.
statusstringoptional
The networking status of the reader. We do not recommend using this field in flows that may block taking payments.
Allowed:offlineonline
defaultError response.
errorobjectrequired

Error handling

reader must be a string no longer than 5000 characters, and amount must be a positive integer expressed in the smallest currency unit when supplied. Each charge or payment_intent identifier must be a string no longer than 5000 characters, while each expand value must also be no longer than 5000 characters.