Stripe: Refund a Charge or a Payment Intent in-person

← Terminal operations · Get started

Operation stripe.postterminalreadersreaderrefundpayment

Provider route: POST /v1/terminal/readers/{reader}/refund_payment. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["terminal"]["postTerminalReadersReaderRefundPayment"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.terminal.postTerminalReadersReaderRefundPayment(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.terminal.post_terminal_readers_reader_refund_payment(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.reader	string	Required within parent	Maximum length: 5000
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Optional	Additional keys: not allowed
body.amount	integer	Optional	A positive integer in cents representing how much of this charge to refund.
body.charge	string	Optional	ID of the Charge to refund. Maximum length: 5000
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.metadata	object	Optional	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`. Additional keys: see wildcard field
body.metadata.*	string	Additional keys
body.payment_intent	string	Optional	ID of the PaymentIntent to refund. Maximum length: 5000
body.refund_application_fee	boolean	Optional	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.
body.refund_payment_config	object	Optional	Configuration overrides for this refund, such as customer cancellation settings.
body.refund_payment_config.enable_customer_cancellation	boolean	Optional
body.reverse_transfer	boolean	Optional	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.

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a Reader — response body

Referenced models: Create a Reader — response body

Schemas

734 more schemas are linked from the tables above, on the schema pages.

Create a Reader — response body

Field	Type	Presence	Description and constraints
$	object	Root	A Reader represents a physical device for accepting payment details. Related guide: [Connecting to a reader](https://docs.stripe.com/terminal/payments/connect-reader)
action	JSON	Optional
action (anyOf 1)	JSON	Alternative	The most recent action performed by the reader.
action (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Reader — response body — action / The most recent action performed by the reader / status: failed, in progress, succeeded
action (anyOf 2)	null	Alternative
device_sw_version	JSON	Optional
device_sw_version (anyOf 1)	string	Alternative	The current software version of the reader. Maximum length: 5000
device_sw_version (anyOf 2)	null	Alternative
device_type	string	Required within parent	Device type of the reader. Known values: bbpos_chipper2x, bbpos_wisepad3, bbpos_wisepos_e, mobile_phone_reader, simulated_stripe_s700, simulated_stripe_s710, simulated_verifone_m425, simulated_verifone_p630, simulated_verifone_ux700, simulated_verifone_v660p, simulated_wisepos_e, stripe_m2, stripe_s700, stripe_s710, verifone_P400, verifone_m425, verifone_p630, verifone_ux700, verifone_v660p
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
ip_address	JSON	Optional
ip_address (anyOf 1)	string	Alternative	The local IP address of the reader. Maximum length: 5000
ip_address (anyOf 2)	null	Alternative
label	string	Required within parent	Custom label given to the reader for easier identification. Maximum length: 5000
last_seen_at	JSON	Optional
last_seen_at (anyOf 1)	JSON	Alternative
last_seen_at (anyOf 1) (anyOf 1)	integer	Alternative	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. Format: unix-time
last_seen_at (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
last_seen_at (anyOf 2)	null	Alternative
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
location	JSON	Optional
location (anyOf 1)	JSON	Alternative	The location identifier of the reader.
location (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
location (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a Location — response body
location (anyOf 2)	null	Alternative
metadata	object	Required within parent	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. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: terminal.reader
serial_number	string	Required within parent	Serial number of the reader. Maximum length: 5000
status	JSON	Optional
status (anyOf 1)	string	Alternative	The networking status of the reader. This value is `null` for mobile readers. We do not recommend using this field in flows that may block taking payments. Known values: offline, online
status (anyOf 2)	null	Alternative

Referenced models: Create a Location — response body, Create a Reader — response body — action / The most recent action performed by the reader / status: failed, in progress, succeeded

Create a Location — response body

Field	Type	Presence	Description and constraints
$	object	Root	A Location represents a grouping of readers. Related guide: [Fleet management](https://docs.stripe.com/terminal/fleet/locations)
address	Model	Required within parent	Expand Create a Location — response body — address
address_kana	Model	Optional	Expand Create a Location — response body — address kana
address_kanji	Model	Optional	Expand Create a Location — response body — address kana
configuration_overrides	string	Optional	The ID of a configuration that will be used to customize all readers in this location. Maximum length: 5000
display_name	string	Required within parent	The display name of the location. Maximum length: 5000
display_name_kana	string	Optional	The Kana variation of the display name of the location. Maximum length: 5000
display_name_kanji	string	Optional	The Kanji variation of the display name of the location. Maximum length: 5000
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadata	object	Required within parent	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. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: terminal.location
phone	string	Optional	The phone number of the location. Maximum length: 5000

Referenced models: Create a Location — response body — address, Create a Location — response body — address kana

Create a Location — response body — address

Field	Type	Presence	Description and constraints
$	object	Root
city	JSON	Optional
city (anyOf 1)	string	Alternative	City, district, suburb, town, or village. Maximum length: 5000
city (anyOf 2)	null	Alternative
country	JSON	Optional
country (anyOf 1)	string	Alternative	Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Maximum length: 5000
country (anyOf 2)	null	Alternative
line1	JSON	Optional
line1 (anyOf 1)	string	Alternative	Address line 1, such as the street, PO Box, or company name. Maximum length: 5000
line1 (anyOf 2)	null	Alternative
line2	JSON	Optional
line2 (anyOf 1)	string	Alternative	Address line 2, such as the apartment, suite, unit, or building. Maximum length: 5000
line2 (anyOf 2)	null	Alternative
postal_code	JSON	Optional
postal_code (anyOf 1)	string	Alternative	ZIP or postal code. Maximum length: 5000
postal_code (anyOf 2)	null	Alternative
state	JSON	Optional
state (anyOf 1)	string	Alternative	State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). Maximum length: 5000
state (anyOf 2)	null	Alternative

Create a Location — response body — address kana

Field	Type	Presence	Description and constraints
$	object	Root
city	JSON	Optional
city (anyOf 1)	string	Alternative	City/Ward. Maximum length: 5000
city (anyOf 2)	null	Alternative
country	JSON	Optional
country (anyOf 1)	string	Alternative	Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Maximum length: 5000
country (anyOf 2)	null	Alternative
line1	JSON	Optional
line1 (anyOf 1)	string	Alternative	Block/Building number. Maximum length: 5000
line1 (anyOf 2)	null	Alternative
line2	JSON	Optional
line2 (anyOf 1)	string	Alternative	Building details. Maximum length: 5000
line2 (anyOf 2)	null	Alternative
postal_code	JSON	Optional
postal_code (anyOf 1)	string	Alternative	ZIP or postal code. Maximum length: 5000
postal_code (anyOf 2)	null	Alternative
state	JSON	Optional
state (anyOf 1)	string	Alternative	Prefecture. Maximum length: 5000
state (anyOf 2)	null	Alternative
town	JSON	Optional
town (anyOf 1)	string	Alternative	Town/cho-me. Maximum length: 5000
town (anyOf 2)	null	Alternative

Create a Reader — response body — action / The most recent action performed by the reader / status: failed, in progress, succeeded print content

Field	Type	Presence	Description and constraints
$	object	Root	Represents a reader action to print content
image	Model	Optional	Expand Create a Reader — response body — action / The most recent action performed by the reader / status: failed, in progress, succeeded print content image
type	string	Required within parent	The type of content to print. Currently supports `image`. Known values: image

Referenced models: Create a Reader — response body — action / The most recent action performed by the reader / status: failed, in progress, succeeded print content image

Policy, approvals and errors

SDK function policy ID: stripe.postterminalreadersreaderrefundpayment. Catalog operation: PostTerminalReadersReaderRefundPayment. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source