close
Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in
OverviewAccept a paymentUpgrade your integration
Online payments
OverviewFind your use caseRecurring payments
In-person payments
Availability
Payment methods
Payment operations
Balances and settlement timeReceiptsRefunds and cancellations
Advanced integrations
Beyond payments

Manage payment methods in settings

Use the Payment Method Settings Sheet to let your customers manage their payment methods in your app settings page.

Note

Use the Payment Method Settings Sheet on an app settings page. For checkout and payments, use In-app Payments, which also has built-in support for saving and displaying payment methods and supports more payment methods than the Payment Method Settings Sheet.

Note

In code, this component is referenced as CustomerSheet for historical reasons. Throughout the documentation, when you see CustomerSheet in code examples, it refers to the Payment Method Settings Sheet.

The Payment Method Settings Sheet is a prebuilt UI component that lets your customers manage their saved payment methods. You can use the Payment Method Settings 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 can set their default payment method stored locally on the device. Use both In-app Payments and the Payment Method Settings Sheet to provide customers a consistent end-to-end solution for saved payment methods.

Accounts v2 API support

The Payment Method Settings Sheet doesn’t support customer-configured Accounts. It only supports Customer objects.

Screenshot of Payment Method Settings Sheet presenting multiple saved payment methods in an iOS app.

The CustomerSession object grants the SDK temporary access to the Customer and provides additional configuration options. These configuration options allow you to customize the behavior of CustomerSheet. A complete list of features exposed on the CustomerSession are in our API docs.

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:

  1. In Xcode, select File > Add Package Dependencies… and enter https://github.com/stripe/stripe-ios-spm as the repository URL.
  2. Select the latest version number from our releases page.
  3. 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.

AppDelegate.swift
Swift
import UIKit
import StripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        StripeAPI.defaultPublishableKey = "pk_test_TYooMQauvdEDq54NiTphI7jx"
        // do any other necessary launch configuration
        return true
    }
}

Note

Use your test keys while you test and develop, and your live mode keys when you publish your app.

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

CustomerSheet only supports cards, US bank accounts, and SEPA Direct Debit.

Add customer endpoints
Server-side

Create two endpoints on your server: one for fetching a CustomerSession client secret, and one to create a SetupIntent for saving a new payment method to the Customer.

  1. Create an endpoint to return a Customer ID and a CustomerSession client secret.
Command Line
curl
Ruby
Python
PHP
Node.js
Java
No results
# 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 sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
  -X "POST"

curl https://api.stripe.com/v1/customer_sessions \
  -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[customer_sheet][enabled]"=true \
  -d "components[customer_sheet][features][payment_method_remove]"=enabled

Note

Integrations with legacy customer ephemeral keys results in saved payment methods having an allow_redisplay value of unspecified. To display these payment methods in addition to payment methods saved while using Customer Sessions, set payment_method_allow_redisplay_filters to ["unspecified", "always"]. For more information, see CustomerSessions.

  1. Create an endpoint to return a SetupIntent configured with the Customer ID.
Command Line
curl
Ruby
Python
PHP
Node.js
Java
No results
# 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 sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
  -X "POST"

curl https://api.stripe.com/v1/setup_intents \
  -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
  -d "customer"="{{CUSTOMER_ID}}" \

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.

Configure the sheet

Next, configure the Payment Method Settings Sheet using the CustomerSheet class with an IntentConfiguration, CustomerSessionClientSecretProvider and a CustomerSheet.Configuration.

var configuration = CustomerSheet.Configuration()

// Configure settings for the CustomerSheet here. For example:
configuration.headerTextForSelectionScreen = "Manage your payment method"

let intentConfiguration = CustomerSheet.IntentConfiguration(setupIntentClientSecretProvider: {
  let json = try await myBackend.createSetupIntent()
  return json["setupIntentClientSecret"]!
})

let customerSheet = CustomerSheet(
      configuration: configuration,
      intentConfiguration: intentConfiguration,
      customerSessionClientSecretProvider: {
        let json = try await myBackend.createCustomerSessionClientSecret()
        return .init(customerId: json["customerId"]!, clientSecret: json["customerSessionClientSecret"]!)
      })

Present the sheet

Present the Payment Method Settings Sheet using CustomerSheet. When the customer dismisses the sheet, the CustomerSheet calls the completion block with a CustomerSheet.SheetResult.

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 back end 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 .selected(PaymentOptionSelection?). The associated value is the selected PaymentOptionSelection, or nil if the user deleted the previously-selected payment method. You can find the full payment method details in the PaymentOptionSelection’s paymentMethod associated value.
  • If the user cancels the sheet, the result is .canceled. The associated value is the original payment method selected prior to opening the customer sheet, as long as that payment method is still available.
  • If an error occurs, the result is .error(Error).

Learn more about how to enable Apple Pay.