Migrate to Stripe iOS SDK 25

Migrate your Swift and Objective-C apps to our latest iOS SDK major version.

This migration guide helps you update your iOS app to use the latest Stripe SDK. It’s especially helpful if you’re coming from old (pre v21) SDK versions.

Requirements

The latest SDK requires Xcode 15 or later. The minimum deployment target is iOS 13.

v25

Migration instructions can be found here.

v24

PaymentSheet

PaymentSheet displays payment methods in either a vertical or horizontal layout. Prior to this major version, PaymentSheet defaulted to a horizontal layout. Now, Stripe optimises the layout automatically. To set a specific layout instead, set the PaymentSheet.Configuration.paymentMethodLayout property to either .horizontal or .vertical.

This example code sets the layout back to horizontal, the previous default.

var configuration = PaymentSheet.Configuration()
configuration.paymentMethodLayout = .horizontal

Basic integration

We no longer support our legacy Basic Integration for collecting credit card and wallet payments.

If your app relies on any of the following APIs, it uses the Basic Integration. Migrate to the Mobile Payment Element, by following this migration guide.

STPCustomerContext
STPPaymentContext
STPPaymentOptionsViewController
STPAddCardViewController
STPShippingAddressViewController

v23

Modules

The SDK is now split into separate modules. You can reduce your app’s bundle size by including only the modules you need.

Module	Features	Compressed size
StripePaymentSheet	Stripe’s pre-built payment UI.	2.7MB
Stripe	Contains all the below frameworks, plus Issuing and Basic Integration.	2.2MB
StripePayments	Bindings for the Stripe Payments API.	1.1MB
StripePaymentsUI	Bindings for the Stripe Payments API, STPPaymentCardTextField, STPCardFormView, and other UI elements.	1.7MB
StripeApplePay	Apple Pay support, including `STPApplePayContext`.	0.4MB

Module installation

Add the selected module (e.g. “StripePaymentSheet”) to the target of your app.

PaymentSheet

To use PaymentSheet, you must explicitly import the StripePaymentSheet module.

Before

After

import Stripe

import StripePaymentSheet

Card field

SDK 23 replaces STPPaymentCardTextField’s .cardParams parameter with .paymentMethodParams, making it easier to collect the customer’s postal code.

In most situations, you can now pass the cardTextField.paymentMethodParams directly to the Stripe API.

Before

After

var cardTextField: STPPaymentCardTextField
// Collect card details
let paymentIntentParams = STPPaymentIntentParams(clientSecret: paymentIntentClientSecret)
let cardParams = cardTextField.cardParams
let paymentMethodParams = STPPaymentMethodParams(card: cardParams, billingDetails: nil, metadata: nil)
paymentIntentParams.paymentMethodParams = paymentMethodParams

var cardTextField: STPPaymentCardTextField
// Collect card details
let paymentIntentParams = STPPaymentIntentParams(clientSecret: paymentIntentClientSecret)
paymentIntentParams.paymentMethodParams = cardTextField.paymentMethodParams

Advanced card field usage

To access the STPPaymentMethodCardParams directly, use .paymentMethodParams.card.

Before

After

var cardTextField: STPPaymentCardTextField
let cardParams = cardTextField.cardParams

var cardTextField: STPPaymentCardTextField
// STPPaymentCardTextField will never return a nil .card
let cardParams = cardTextField.paymentMethodParams.card!

cardTextField.paymentMethodParams returns a copy. Never set cardTextField.paymentMethodParams.card directly. If you need to set the card information, set cardTextField.paymentMethodParams to a new instance of STPPaymentMethodParams.

Before

After

var cardTextField: STPPaymentCardTextField
cardTextField.cardParams = myCardParams

var cardTextField: STPPaymentCardTextField
let paymentMethodParams = STPPaymentMethodParams(card: myCardParams, billingDetails: nil, metadata: nil)
cardTextField.paymentMethodParams = paymentMethodParams

v22

The minimum iOS deployment target was changed to iOS 12 in this version.

v21

The SDK was re-written in Swift, and some manual changes are required.

Cocoapods users must update to Cocoapods 1.10 or later.

Stripe class

The Stripe class is now named StripeAPI.

Before

After

Stripe.setDefaultPublishableKey("pk_test_TYooMQauvdEDq54NiTphI7jx"
)
Stripe.additionalEnabledApplePayNetworks = [.JCB]

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
  return Stripe.handleURLCallback(with: url)
}

StripeAPI.defaultPublishableKey = "pk_test_TYooMQauvdEDq54NiTphI7jx"

StripeAPI.additionalEnabledApplePayNetworks = [.JCB]

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
  return StripeAPI.handleURLCallback(with: url)
}

Properties

Some setX() functions are now properties in Swift.

Before

After

Stripe.setDefaultPublishableKey("pk_test_TYooMQauvdEDq54NiTphI7jx"
)

StripeAPI.defaultPublishableKey = "pk_test_TYooMQauvdEDq54NiTphI7jx"

STPPaymentConfiguration

STPPaymentConfiguration’s additionalPaymentOptions setting is now two Bools: applePayEnabled and fpxEnabled.

Before

After

STPPaymentConfiguration.shared.additionalPaymentOptions = [.fpx]

STPPaymentConfiguration.shared.applePayEnabled = false
STPPaymentConfiguration.shared.fpxEnabled = true

Error handling

Global STPError constants are now in the STPError class.

Before

After

if (error.userInfo[STPCardErrorCodeKey] == STPInvalidNumber) {
  return "Invalid card number"
}

if (error.userInfo[STPError.cardErrorCodeKey] == STPCardErrorCode.invalidNumber) {
  return "Invalid card number"
}

STPTheme

STPTheme.default() is now STPTheme.defaultTheme.

Before

After

STPTheme.default().primaryForegroundColor = .systemRed

STPTheme.defaultTheme.primaryForegroundColor = .systemRed