# React Native SDK migration guide

Learn how to migrate your Terminal React Native integration to version 6.0.0.

See [Design an integration](https://docs.stripe.com/terminal/designing-integration.md) to learn how to get started.

This guide covers migrating an existing Terminal React Native integration from `0.0.1-beta.33` to `6.0.0`, the SDK’s first generally available (GA) release. Starting with `6.0.0`, this SDK’s own version numbers track the bundled native Terminal SDK’s version—expect `6.1.0`, `6.2.0`, `7.0.0`, and so on after this release, rather than further `0.0.1-beta.X` previews.

If you’re already on `0.0.1-beta.34`, you’ve made most of these changes already. It’s already bundled native Terminal iOS and Android SDKs 6.0.0 and introduced most of the breaking changes below. Only the changes marked **(new in `6.0.0`)** are new to you. After installing the new package version, make the following changes to adopt the updated APIs. See the [`0.0.1-beta.34` changelog entry](https://github.com/stripe/stripe-terminal-react-native/blob/main/CHANGELOG.md#001-beta34) for its full release details.

Before you migrate, review the [Terminal SDK versioning and support policy](https://docs.stripe.com/terminal/references/sdk-versioning.md) to understand supported SDK versions, patch support timelines, and end-of-life enforcement.

## Update your platform requirements

Update your app to [the supported React Native and native toolchains](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=react-native), including React Native 0.83 or later, React 19.2 or later, an iOS deployment target of 16.0 or later, and Android `compileSdkVersion` 35 or later. React Native 0.83 requires the [New Architecture](https://reactnative.dev/architecture/landing-page) (Fabric and TurboModules).

After installing the SDK package, rebuild both native apps. On iOS, use `yarn ios` for a React Native Community CLI app or `npx expo run:ios` for an Expo app to install native dependencies and build. CocoaPods autolinks the React Native module, and the module configures and embeds the native Terminal iOS SDK from its Swift package. Remove any separately added `StripeTerminal` pod or Swift package dependency from your app to avoid duplicate dependencies.

## Update initialization, imports, and logging

Pass the required `localeConfig` prop to `StripeTerminalProvider` to configure API error message localization:

```tsx
<StripeTerminalProvider
  tokenProvider={fetchTokenProvider}
  localeConfig={{ type: 'cardLanguagePreferenceIfAvailable' }}
>
  <App />
</StripeTerminalProvider>
```

To use a fixed language, pass `{ type: 'hardcoded', locale: 'en-US' }`. The SDK applies this configuration during initialization. Restart the app to change it for a subsequent session.

Replace imports of the removed `StripeTerminalSdk` runtime export with `StripeTerminalProvider` and `useStripeTerminal`, or `withStripeTerminal` for class components. Replace the removed `StripeTerminalSdkType` type with `WithStripeTerminalProps`.

If you pass `logLevel: 'verbose'` to `StripeTerminalProvider`, its console logs now contain only the SDK operation or event name, without payload details. Review debugging code that depends on those payloads, and handle returned errors directly.

## Update payment and collection parameters

The default `createPaymentIntent` capture method changes from `manual` to `automatic_async`. If your integration authorizes a payment and captures it separately on your server, explicitly set `captureMethod: 'manual'`:

```tsx
const { paymentIntent, error } = await createPaymentIntent({
  amount: 1000,
  currency: 'usd',
  captureMethod: 'manual',
});
```

When calling `collectSetupIntentPaymentMethod` or `processSetupIntent`, pass `allowRedisplay` as `always` or `limited` according to the customer’s consent and intended future use. See [Save cards for later use](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md?terminal-sdk-platform=react-native) for consent requirements.

> Starting with `6.0.0`, `CustomerCancellation` and `CollectionReason` no longer accept `'unspecified'`. Omit the field instead to use its native default: `'enableIfAvailable'` for `customerCancellation`, `'saveCard'` for `collectionReason`.

## Update response handling

Update field access, TypeScript annotations, and test fixtures for the following response changes. Check optional fields before using them.

| Response | Change |
| --- | --- |
| `PaymentIntent` | Replace the `charges` array with `latestCharge` and `latestChargeId`. `id`, `latestCharge`, and `latestChargeId` can all be absent. |
| `PaymentMethodOptions` **(new in `6.0.0`)** | Pass requests with `CreatePaymentIntentParams.paymentMethodOptions` using `PaymentMethodOptionsParams`. Read responses from `PaymentIntent.paymentMethodOptions` and `SetupIntent.paymentMethodOptions` using `PaymentMethodOptions`. |
| `PaymentMethod.cardPresentDetails` and `interacPresentDetails` | Both now use the shared `PaymentMethodCardPresentDetails` type. Read transaction details from `latestCharge.paymentMethodDetails`. Payment-method-specific details and `customer` can be absent. |
| `CardPresentDetails` | `expMonth` and `expYear` are numbers. `preferredLocales`, `issuer`, `iin`, `description`, and `wallet` can be absent. |
| `ReceiptDetails` | `accountType` and `authorizationCode` can be absent. Use the singular `terminalVerificationResult` field on both platforms. |
| `SetupIntent.latestAttempt` | `paymentMethodDetails` and its `cardPresent` and `interacPresent` fields can be absent. Payment method types use React Native values such as `cardPresent` and `interacPresent`. |
| `Refund` | `id` can be absent. Handle `canceled` and `requiresAction` statuses, and inspect `nextAction` when present. |
| `Reader.Type` | `id`, `serialNumber`, and `batteryStatus` can be absent. `isCharging` is a Boolean. The reader’s network `status` can be `unknown`, and battery status values use lowercase on both platforms. |

For example, read receipt details from the latest charge:

```tsx
const receipt = paymentIntent.latestCharge?.paymentMethodDetails?.cardPresentDetails?.receipt;
```

Update your type annotations for both renamed types for `6.0.0`:

- Request annotations: rename `PaymentMethodOptions` to `PaymentMethodOptionsParams`.
- Response annotations: rename `PaymentMethodOptionsResponse` to `PaymentMethodOptions`. `PaymentMethodOptions` now names the *response*  format—it no longer refers to the flat request type it did in `0.0.1-beta.34`. An existing `PaymentMethodOptions`-annotated request literal won’t compile after upgrading. Update it to `PaymentMethodOptionsParams`.

On the response type, `cardPresent` is the named `CardPresentOptions` type, and `cardPresent` and its extended-authorization, incremental-authorization, and partial-authorization flags are all optional.

## Update method results and error codes

`getConnectedReader()` returns a reader directly, or `null` when no reader is connected. It rejects native bridge failures. Add error handling around this method and the `getConnectionStatus`, `getPaymentStatus`, and `getOfflineStatus` getters, which also reject failures instead of returning an error object:

```tsx
try {
  const reader = await getConnectedReader();
  if (reader === null) {
    // Show your reader connection flow.
    return;
  }
  // Use the connected reader.
} catch (error) {
  // Handle the failed lookup before retrying.
}
```

When `processSetupIntent` fails, read the updated `SetupIntent` from `error.setupIntent`, when available, instead of the result’s top-level `setupIntent`.

Update these result types and error codes:

- For `6.0.0`, replace `Reader.ConnectionStatus` with the top-level `ConnectionStatus`. Both `getConnectionStatus()` and the `onDidChangeConnectionStatus` callback now use it.
- `GetConnectedReaderType` describes the resolved value of `getConnectedReader()` as `Reader.Type | null`. If your integration imports `GetConnectedReaderResultType`, replace that import and its type annotations with `GetConnectedReaderType`.
- `DiscoverReadersResultType` and `CancelDiscoveringResultType` describe resolved values. Use `Promise<DiscoverReadersResultType>` or `Promise<CancelDiscoveringResultType>` when annotating an asynchronous wrapper.
- The `error` field is optional on successful `disconnectReader`, `rebootReader`, and `clearReaderDisplay` results.
- For `supportsReadersOfType`, await the result and check `error` before reading `readerSupportResult`. A native unsupported-reader result includes `false`, while a parameter or bridge failure can omit the Boolean.
- Replace `PRINTER_LOW_BATTERY` with `READER_BATTERY_LOW`. Handle `CANCELED_BY_READER` for payment flows canceled from the reader and `INVALID_INSTALLMENT_PLAN` for invalid Android installment plans.
- Replace `CollectDataType.UNKNOWN` with a supported collection type: `CollectDataType.MAGSTRIPE` or `CollectDataType.NFC_UID`.

## Update reader callbacks and Tap to Pay configuration

`onDidReportReaderSoftwareUpdateProgress` receives a number between `0` and `1`. `onDidFinishInstallingUpdate` receives separate optional `update` and `error` arguments, replacing the single result object. Both arguments can be present when an update fails, or absent when no update is available:

```tsx
const terminal = useStripeTerminal({
  onDidReportReaderSoftwareUpdateProgress: (progress) => {
    setCurrentProgress((progress * 100).toFixed(0));
  },
  onDidFinishInstallingUpdate: (update, error) => {
    if (error) {
      // Handle the failure. The update can also be available.
      return;
    }
    // Handle completion. The update can be undefined.
  },
});
```

Remove imports of `UpdateSoftwareResultType`. When constructing `Reader.SoftwareUpdate` fixtures, include `isTestUpdate`, `requiredAt`, and `components`.

Update other callback annotations and class-component event listeners:

- `onDidStartReaderReconnect(reader, reason)` and `onDidDisconnect(reason)` always receive a reason.
- `onDidForwardPaymentIntent(paymentIntent, error)` can omit the error when forwarding succeeds. `onDidForwardingFailure(error)` always receives an error.
- The provider’s `FINISH_INSTALLING_UPDATE` event uses `(update, error)`, `START_READER_RECONNECT` uses `(reader, reason)`, and `READER_RECONNECT_FAIL` uses `(reader)`.

For Tap to Pay on Android, rename `TapToPayUxConfiguration.darkMode` to `theme` and `colors` to `colorScheme`. Only the property names change — the value type, `DarkMode`, keeps its name. When you omit `theme`, the payment UI follows the system theme. See [UX configuration](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=android#ux-configuration).

## Validate your migration

Build your app for iOS and Android, then test the flows your integration uses. Confirm that initialization succeeds, disconnected reader lookups return `null`, and capture behavior matches your order flow. Exercise payment and SetupIntent failures, reader updates and reconnection, offline forwarding, and refunds so your code handles optional resources and callback arguments.
