Migrate from the Basic Integration to the Mobile Payment Element

Upgrade your legacy mobile SDK integration before we remove it from the SDK.

From 4 November 2024, Stripe’s iOS SDK, Android SDK, and React Native SDK no longer support our legacy Basic Integration for collecting credit card and wallet payments.

To use SDK versions published after 4 November 2024, you must remove the Basic Integration code references in your app and upgrade to the Mobile Payment Element.
You can still process payments through older versions of the SDK, but you risk missing critical security enhancements and new features.

Upgrading to the Mobile Payment Element gives you access to:

Over 100 global payment methods including Link, Stripe’s accelerated checkout
The ability to display saved payment methods to buyers for future purchases
The Appearance API, which allows you to customise the look and feel to match your app

Example of benefits gained when migrating from Basic Integration to Payment Element

In iOS, Basic Integration includes:

STPCustomerContext
STPPaymentContext
STPPaymentOptionsViewController
STPAddCardViewController
STPShippingAddressViewController

In Android, Basic Integration includes:

CustomerSession
PaymentSession
PaymentMethodsActivity
AddPaymentMethodActivity
PaymentFlowActivity

Migrate to the Mobile Payment Element

The Basic Integration is generally used in one of two ways:

Checkout page: Users enter their credit card, then click a button in your app to complete their purchase.
Wallet: Users add a credit card to your app, then use that credit card to pay later in a different flow.

Select the tab below that matches your use case, either Checkout page or a wallet:

Use the following integration guides to implement the Mobile Payment Element on a checkout page in your apps:

The integration guides linked above differ from the default Mobile Payment Element integration guide in a few important ways.

Flow Controller

The Mobile Payment Element has a variant called “Flow Controller” (imported from the SDK as PaymentSheet.FlowController). As with the Basic Integration, the Flow Controller lets you collect payment details in the sheet, then process the payment when your user taps a final pay button in your checkout.

Intent creation time

When migrating from the Basic Integration to the Mobile Payment Element, create the Intent after rendering the Mobile Payment Element by providing an PaymentSheet.IntentConfiguration object to PaymentSheet. Set the mode property in your PaymentSheet.IntentConfiguration object to payment, and provide the amount and currency for the transaction.

Set up for future usage

The Basic Integration lets users add cards to their account in your mobile application. To get this same behaviour from PaymentSheet.FlowController, set the setupFutureUsage parameter in your PaymentSheet.IntentConfiguration object to onSession.

Check for other legacy dependencies

Upgrading to the Mobile Payment Element requires you to update other dependencies within your mobile integration. Review the following sections to make sure your migration is comprehensive.

Migrate from the Charges API

If your integration still uses the Charges API with tokens, you must migrate to the Intents API. The Mobile Payment Element integration guide linked above includes details on how to use Intents. You can also review Migrating to the Payment Intents API for more details.

Convert your configuration

The Basic Integration uses a configuration object to customise your integration (STPPaymentConfiguration for iOS, and PaymentSessionConfig for Android). Convert your Basic Integration configuration to a PaymentSheet.Configuration to customise Mobile Payment Element.