# Customization

Configure payment methods, transaction history, refund capabilities, and other settings for Terminal ready-made apps.

Configure standalone mode and the Stripe Terminal app using the Dashboard. On a reader, changes apply after you restart the device. In the Stripe Terminal app, they apply after you close and reopen the app.

These settings are shared between the Stripe Terminal app and standalone mode readers registered to the same location.

For more details on Terminal configurations, see [Terminal configurations](https://docs.stripe.com/terminal/fleet/configurations-overview.md).

Configure standalone mode and the Stripe Terminal app with the `standalone` hash on a Terminal [Configuration](https://docs.stripe.com/api/terminal/configuration.md) object (preview access required). Shared fields apply to both the Stripe Terminal app and standalone mode readers registered to the same Location. Fields marked “standalone mode only” don’t apply to the Stripe Terminal app. Fields:

- `enabled` (boolean): Turn standalone mode on for the Configuration.
- `payment_settings.currency` (string): Default currency, such as `usd`.
- `payment_settings.payment_method_types` (array): Accepted methods, such as `card_present`.
- `business_settings.statement_descriptor` (string): Statement descriptor for standalone payments.
- `business_settings.statement_descriptor_suffix` (string): Statement descriptor suffix for standalone card payments.
- `payment_settings.capture_method` (string): `automatic_async` (default), `automatic`, or `manual`.
- `payment_settings.payment_method_options.card_present.capture_method` (string): Set to `manual_preferred` to prefer manual capture for card-present payments.
- `payment_settings.payment_method_options.card_present.request_incremental_authorization` (string): `if_available` or `never`.
- `payment_settings.payment_method_options.card_present.request_extended_authorization` (string): `if_available` or `never`.
- `payment_settings.connect.account` (string): Standalone mode only. The connected account ID.
- `payment_settings.connect.use_as_settlement_merchant` (string): Standalone mode only. `enabled` or `disabled`.
- `payment_settings.connect.use_as_transfer_destination` (string): Standalone mode only. `enabled` or `disabled`.
- `reader_security.transaction_history.availability` (string): `enabled` (default) or `disabled`.
- `reader_security.transaction_history.scope` (string): `location` (default), `all_in_person`, or `all`.
- `reader_security.refunds.availability` (string): Standalone mode only. `enabled` (default), `enabled_with_passcode`, or `disabled`. In the Stripe Terminal app, restrict refunds with the Terminal Operator role instead.
- `reader_security.refunds.passcode` (string): Standalone mode only. Required when `availability` is `enabled_with_passcode`.

On-reader tipping is standalone mode only; it isn’t supported in the Stripe Terminal app.

## Update a configuration

#### Dashboard

1. [Choose default or location-specific custom settings](https://docs.stripe.com/terminal/fleet/configurations-overview.md?dashboard-or-api=dashboard).
2. Under **Ready-made apps**, select **Ready-made payments**, **Refunds and transaction history**, or **Payment descriptors**. For custom settings, use **Add settings** if the setting isn’t listed.
3. Edit the values using the instructions in this guide. Tipping is under **Payment** > **Tipping** instead of **Ready-made apps**.
4. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

To apply the changes, restart the reader or close and reopen the Stripe Terminal app.

## Payment settings

### Accepted payment methods

Standalone mode and the Stripe Terminal app support [Terminal-supported card brands](https://docs.stripe.com/terminal/payments/collect-card-payment/supported-card-brands.md#payment-method-availability) and [additional payment methods](https://docs.stripe.com/terminal/payments/additional-payment-methods.md), such as [Affirm](https://docs.stripe.com/terminal/payments/additional-payment-methods.md#affirm), [WeChat Pay](https://docs.stripe.com/terminal/payments/additional-payment-methods.md#wechat-pay), and [PayNow](https://docs.stripe.com/terminal/payments/additional-payment-methods.md#paynow).

Some payment methods require activation in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods) before you can use them.

When multiple non-card payment methods are enabled, the payment flow displays a **More ways to pay** button. If only one additional payment method is enabled, the payment flow displays it directly. Payment method availability depends on the transaction amount and the country of the location. For example, Affirm only appears when the payment amount falls within its supported range.

#### Dashboard

1. Under **Ready-made apps** > **Ready-made payments**, select **Payment method types** and **Currency**.
2. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

### Capture method

Configure how payments are captured. The capture method determines when funds are collected from the customer’s payment method.

- **`automatic_async`** (default): Stripe automatically captures the payment shortly after authorization. Use this for standard transactions where you don’t need to adjust the amount after the customer pays.
- **`manual_preferred`**: The payment is authorized but not immediately captured for supported payment methods. If a payment method doesn’t support manual capture, it’ll be automatically captured. You must explicitly [capture](https://docs.stripe.com/api/payment_intents/capture.md) the payment later using the API or Dashboard. Use this when you need to adjust the final amount after authorization, such as with incremental or extended authorizations.

#### Dashboard

1. Under **Ready-made apps** > **Ready-made payments**, select **Automatic async** or **Manual preferred** under **Capture method**.
2. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

### Incremental and extended authorization

If you select `manual_preferred` for card-present payments under [Capture method](https://docs.stripe.com/terminal/payments/ready-made-apps/customization.md#capture-method), you can optionally choose to [increment](https://docs.stripe.com/terminal/features/incremental-authorizations.md) or [extend](https://docs.stripe.com/terminal/features/extended-authorizations.md) an authorization.

> Incremental authorization requires using the API—you can’t increment a payment from the Dashboard, the reader, or the Stripe Terminal app. After the payment is incremented, or if you’re only using extended authorization, you can capture the payment from the Dashboard or using the API.

#### Dashboard

1. Under **Ready-made apps** > **Ready-made payments** > **Payment method types**, select **Card-present payments**.
2. Under **Ready-made apps** > **Ready-made payments** > **Capture method**, select **Manual preferred**.
3. After the **Incremental authorization** and **Extended authorization** controls appear, select the options you need.
4. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

To capture a payment after it has been incremented or extended:

1. Go to the [Payments](https://dashboard.stripe.com/payments) page in the Dashboard.
2. Click the uncaptured payment to open the payment details.
3. Click **Capture**.

### Payment descriptors

To customize bank-statement descriptors for ready-made payments at the selected scope:

1. Select **Ready-made apps** > **Payment descriptors**. The editor starts with the effective configured static descriptor, or your account’s statement descriptor if none is configured.
2. Edit **Static descriptor** and the optional **Dynamic suffix**.
3. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

## Transaction history and refunds

### Transaction history

Transaction history lets you view past transactions and initiate refunds directly on the device. You can control the scope of visible transactions.

- **`enabled`** (default): Displays transaction history on the device.
- **`disabled`**: Transaction history isn’t available on the device.

When enabled, you can set the scope of visible transactions:

- **`location`** (default): Transactions processed at the same Location are visible.
- **`all_in_person`**: All in-person transactions for the account are visible.
- **`all`**: All transactions for the account are visible, including online transactions. Recommended for unified commerce cases where you want to allow customers to buy online and return in store.

Transaction history lists transactions from the past 7 days. When you search, it returns matching transactions within the configured scope, regardless of date. Search matches the beginning of an internal note, so a transaction appears only when your search term is at the start of its note. For example, searching for “first” returns a note of “First” but not “No First”.

#### Dashboard

1. Under **Ready-made apps** > **Refunds and transaction history**, turn on **Allow transaction history**.
2. Select the scope of visible transactions.
3. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

### Refunds

In the Stripe Terminal app, you restrict refunds with the Terminal Operator role instead of a passcode. Add a user with the Terminal Operator role to prevent them from creating refunds in the app or accessing the Stripe Dashboard. The passcode options described here apply to standalone mode on a reader.

Enable refunds on the reader to allow initiating refunds directly from the transaction history. You can optionally require a passcode to authorize refunds.

- **`enabled`** (default): Refunds are available on the reader without a passcode.
- **`enabled_with_passcode`**: Refunds require a passcode to authorize on the reader.
- **`disabled`**: Refunds are not available on the reader.

Stripe restricts access to passcode management based on user roles. Only users with Super Administrator, Administrator, Terminal Specialist, or Developer roles can view passcodes. Only users with Super Administrator, Administrator, or Terminal Specialist roles can modify passcodes.

> Make sure your admin passcodes are secure and not easily guessable. Avoid common patterns like sequential numbers (12345) or repeated digits (11111).

#### Dashboard

1. Under **Ready-made apps** > **Refunds and transaction history**, turn on **Allow transaction history**. Refund controls depend on transaction history being enabled.
2. Turn on **Allow refunds**.
3. To require a passcode on the reader, turn on **Require PIN** and enter a five-digit **Refund PIN**.
4. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

## Tipping

Tipping isn’t supported in the Stripe Terminal app. These settings apply to standalone mode on a reader.

Enable on-reader tipping to let customers add a tip during the payment flow. You can configure tip amounts as percentages, fixed amounts, or allow custom tip entry.

#### Dashboard

1. Select **Payment** > **Tipping** and follow the [tipping configuration instructions](https://docs.stripe.com/terminal/fleet/tipping.md?dashboard-or-api=dashboard#from-the-location-details-page). Use the same tipping option for all currencies.
2. Click **Save {currency} tip values** for each currency. Saving values in the panel doesn’t apply them to readers.
3. For default settings, click **Apply changes**. For custom settings, click **Apply customizations**, then **Apply custom settings** in the confirmation dialog.

For more details on tipping configuration, see [On-reader tipping](https://docs.stripe.com/terminal/features/collecting-tips/on-reader.md).

## See also

- [Use standalone mode with Connect](https://docs.stripe.com/terminal/payments/ready-made-apps/connect.md)
- [Terminal configurations](https://docs.stripe.com/terminal/fleet/configurations-overview.md)
- [Manage locations and zones](https://docs.stripe.com/terminal/fleet/locations-and-zones.md)
