Integrate the Customer Sheet
Offer a prebuilt UI for your customers to manage their saved payment methods.
The Customer Sheet is a prebuilt UI component that lets your customers manage their saved payment methods. You can use the Customer Sheet UI outside of a checkout flow, and the appearance and styling is customizable to match the appearance and aesthetic of your app. Customers can add and remove payment methods, which get saved to the customer object, and set their default payment method stored locally on the device. Use both the Mobile Payment Element and the Customer Sheet to provide customers a consistent end-to-end solution for saved payment methods.
CustomerAdapter uses Customer Ephemeral Keys and serves as a bridge to help users of legacy products (such as the Basic Integration) adopt CustomerSheet more quickly. If you’re starting a new integration, we recommend adopting CustomerSession over Customer Ephemeral Keys.
Set up Stripe
First, you need a Stripe account. Register now.
The Stripe iOS SDK is open source, fully documented, and compatible with apps supporting iOS 13 or above.
To install the SDK, follow these steps:
- In Xcode, select File > Add Packages… and enter
https://github.
as the repository URL.com/stripe/stripe-ios-spm - Select the latest version number from our releases page.
- Add the StripePaymentSheet product to the target of your app.
Note
For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.
Configure the SDK with your Stripe publishable key on app start. This enables your app to make requests to the Stripe API.
import UIKit import StripePaymentSheet @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { StripeAPI.defaultPublishableKey =
// do any other necessary launch configuration return true } }"pk_test_TYooMQauvdEDq54NiTphI7jx"
Enable payment methods
View your payment methods settings and enable the payment methods you want to support. You need at least one payment method enabled to create a SetupIntent.
By default, Stripe enables cards and other prevalent payment methods that can help you reach more customers, but we recommend turning on additional payment methods that are relevant for your business and customers. See Payment method support for product and payment method support, and our pricing page for fees.
Note
At this time, CustomerSheet only supports cards and US bank accounts.
Add Customer endpointsServer-side
Create two endpoints on your server: one for fetching a Customer’s ephemeral key, and one to create a SetupIntent for saving a new payment method to the Customer.
- Create an endpoint to return a Customer ID and an associated ephemeral key. You can view the API version used by the SDK here.
# Create a Customer (skip this and get the existing Customer ID if this is a returning customer) curl https://api.stripe.com/v1/customers \ -u
: \ -X "POST" curl https://api.stripe.com/v1/ephemeral_keys \ -usk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \sk_test_4eC39HqLyjWDarjtT1zdp7dc
- Create an endpoint to return a SetupIntent configured with the Customer ID.
# Create a Customer (skip this and get the existing Customer ID if this is a returning customer) curl https://api.stripe.com/v1/customers \ -u
: \ -X "POST" curl https://api.stripe.com/v1/setup_intents \ -usk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d "customer"="{{CUSTOMER_ID}}" \sk_test_4eC39HqLyjWDarjtT1zdp7dc
If you only plan to use the payment method for future payments when your customer is present during the checkout flow, set the usage parameter to on_session to improve authorization rates.
Create a Customer adapterClient-side
A StripeCustomerAdapter
enables a CustomerSheet
to communicate with Stripe. On the client, configure a StripeCustomerAdapter
with providers that make requests to these endpoints on your server.
import StripePaymentSheet let customerAdapter = StripeCustomerAdapter(customerEphemeralKeyProvider: { let json = await myBackend.getCustomerEphemeralKey() return CustomerEphemeralKey(customerId: json["customerId"]!, ephemeralKeySecret: json["ephemeralKeySecret"]!) }, setupIntentClientSecretProvider: { let json = await myBackend.getSetupIntentForCustomer() return json["setupIntentClientSecret"]! })
Configure the sheet
Next, configure the Customer Sheet with your StripeCustomerAdapter
and a CustomerSheet.Configuration.
var configuration = CustomerSheet.Configuration() // Configure settings for the CustomerSheet here. For example: configuration.headerTextForSelectionScreen = "Manage your payment method" let customerSheet = CustomerSheet(configuration: configuration, customer: customerAdapter)
Present the sheet
Present the Customer Sheet. When the customer dismisses the sheet, the Customer Sheet calls the completion block with a CustomerSheet.
.
import StripePaymentSheet customerSheet.present(from: self, completion: { result in switch result { case .canceled(let paymentOption), .selected(let paymentOption): // Configure your UI based on the payment option self.paymentLabel.text = paymentOption?.displayData().label ?? "None" // Optional: Send the selected payment method ID to your backend for advanced use cases // like charging a customer when not present in your app if let paymentOption = paymentOption { switch paymentOption { case .paymentMethod(let paymentMethod, let paymentOptionDisplayData): MyBackend.setDefaultPaymentMethod(paymentMethod.stripeId) case .applePay(paymentOptionDisplayData: let paymentOptionDisplayData): MyBackend.setDefaultPaymentMethodIsApplePay() } } case .error(let error): // Show the error in your UI } })
- If the customer selects a payment method, the result is
.
. The associated value is the selected PaymentOptionSelection, orselected(PaymentOptionSelection?) nil
if the user deleted the previously-selected payment method. You can find the full payment method details in the PaymentOptionSelection’spaymentMethod
associated value. - If the user cancels the sheet, the result is
.
. The associated value is the original payment method selected prior to opening the customer sheet, as long as that payment method is still available.canceled - If an error occurs, the result is
.
.error(Error)
Learn more about how to enable Apple Pay.