Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
About Stripe payments
Upgrade your integration
Payments analytics
Online payments
OverviewFind your use caseManaged Payments
Use Payment Links
Build a checkout page
Build an advanced integration
Build an in-app integration
    Overview
    Payment Sheet
      Accept in-app payments
      Add custom payment methods
      Customize look and feel
      Finalize payments on the server
      Save payment details during payment
      Set up future payments
      Filter card brands
    Embedded Payment Element
    Link out for in-app purchases
    Collect addresses
    US and Canadian cards
Payment methods
Add payment methods
Manage payment methods
Faster checkout with Link
Payment interfaces
Payment Links
Checkout
Web Elements
In-app Elements
Payment scenarios
Handle multiple currencies
Custom payment flows
Flexible acquiring
Orchestration
In-person payments
Terminal
Beyond payments
Incorporate your company
Crypto
Financial Connections
Climate
HomePaymentsBuild an in-app integrationPayment Sheet

Accept in-app payments

Build a customized payments integration in your iOS, Android, or React Native app using the Payment Sheet.

The Payment Sheet is a customizable component that displays a list of payment methods and collects payment details in your app using a bottom sheet.

A PaymentIntent flow allows you to create a charge in your app. When confirming the charge, you can optionally save payment methods. In this integration, you render the Payment Sheet, create a PaymentIntent, and confirm a charge in your app.

Set up Stripe
Server-side
Client-side

Server-side

This integration requires endpoints on your server that talk to the Stripe API. Use our official libraries for access to the Stripe API from your server:

Command Line
Ruby
# Available as a gem sudo gem install stripe
Gemfile
Ruby
# If you use bundler, you can add this line to your Gemfile gem 'stripe'

Client-side

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.

You also need to set your publishable key so that the SDK can make API calls to Stripe. To get started, you can hardcode the publishable key on the client while you’re integrating, but fetch the publishable key from your server in production.

// Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys STPAPIClient.shared.publishableKey =
"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 PaymentIntent.

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.

Set up a return URL
Client-side

The customer might navigate away from your app to authenticate (for example, in Safari or their banking app). To allow them to automatically return to your app after authenticating, configure a custom URL scheme and set up your app delegate to forward the URL to the SDK. Stripe doesn’t support universal links.

SceneDelegate.swift
Swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) { guard let url = URLContexts.first?.url else { return } let stripeHandled = StripeAPI.handleURLCallback(with: url) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } }

Additionally, set the returnURL on your PaymentSheet.Configuration object to the URL for your app.

var configuration = PaymentSheet.Configuration() configuration.returnURL = "your-app://stripe-redirect"

Collect payment details
Client-side

We offer two styles of integration. Choose one to continue.

PaymentSheet PaymentSheet.FlowController
PaymentSheet
PaymentSheet.FlowController
Displays a sheet to collect payment details and complete the payment. The button in the sheet says Pay $X and completes the payment. Displays a sheet to collect payment details only. The button in the sheet says Continue and returns the customer to your app, where your own button completes payment.

This integration assumes your checkout screen has two buttons—a “Payment Method” button that presents the PaymentSheet to collect payment details and a “Buy” button that completes the payment.

Initialize PaymentSheet.FlowController

When your checkout screen loads, initialize PaymentSheet.FlowController with a PaymentSheet.Configuration and a PaymentSheet.IntentConfiguration. The Configuration object contains general-purpose configuration for PaymentSheet that usually don’t change between payments, like returnURL. The IntentConfiguration object contains details about the specific payment, like the amount and currency, as well as a confirmHandler callback—for now, leave its implementation empty.

After PaymentSheet.FlowController initializes, update your “Payment Method” button with its paymentOption. This property contains an image and label representing the customer’s initially selected, default payment method.

class MyCheckoutVC: UIViewController { func loadCheckout() { let intentConfig = PaymentSheet.IntentConfiguration( mode: .payment(amount: 1099, currency: "USD") ) { [weak self] _, _, intentCreationCallback in self?.handleConfirm(intentCreationCallback) } var configuration = PaymentSheet.Configuration() configuration.returnURL = "your-app://stripe-redirect" // Use the return url you set up in the previous step PaymentSheet.FlowController.create( intentConfiguration: intentConfig, configuration: configuration ) { [weak self] result in switch result { case .failure(let error): print(error) case .success(let paymentSheetFlowController): self?.paymentSheetFlowController = paymentSheetFlowController // Update your UI paymentSheetFlowController.paymentOption.image and paymentSheetFlowController.paymentOption.label } } } func handleConfirm(_ intentCreationCallback: @escaping (Result<String, Error>) -> Void) { // ...explained later } }

Present PaymentSheet

When a customer taps your “Payment Method” button, call presentPaymentOptions to collect payment details. When this completes, update your UI again with the paymentOption property.

paymentSheetFlowController.presentPaymentOptions(from: self) { // Update your UI using paymentSheetFlowController.paymentOption }

Optional Update payment details

If the customer performs actions that change the payment details (for example, applying a discount code or editing their cart), update the PaymentSheet.FlowController instance with the new values. This makes sure the correct values are shown in our UI (for example, the pay button, the Apple Pay UI), the appropriate payment methods display, and so on. By updating the instance instead of re-initializing the PaymentSheet.FlowController, the payment sheet preserves the customer’s payment details.

Call the update method with the updated IntentConfiguration object. While the update is in progress, don’t call present or confirm on the PaymentSheet.FlowController (for example, disable your “Buy” and “Payment method” buttons).

When the update completes, update your UI with the paymentOption property in case the customer’s previously selected payment method is no longer available. If the update failed, retry it.

// Create an updated IntentConfiguration var updatedIntentConfig = oldIntentConfig updatedIntentConfig.amount = 999 // Disable your "Buy" and "Payment method" buttons and call `update` paymentSheetFlowController.update(intentConfiguration: updatedIntentConfig) { [weak self] error in if error != nil { // You must retry - until the update succeeds, the customer can't pay or select a payment method. // For example, you can automatically retry the update with an exponential back-off, or present the user with an alert that retries the update. } else { // Re-enable your "Buy" and "Payment method" buttons // Update your UI using paymentSheetFlowController.paymentOption.image and paymentSheetFlowController.paymentOption.label } }

Confirm the payment

When the customer taps your Buy button, call paymentSheetFlowController.confirm. This calls the confirmHandler callback you passed to PaymentSheet.IntentConfiguration with an STPPaymentMethod object representing the customer’s payment details.

Implement this callback to send a request to your server. Your server creates a PaymentIntent and returns its client secret (explained in the next step).

When the request returns, call the intentCreationCallback with your server response’s client secret or an error. The PaymentSheet confirms the PaymentIntent using the client secret.

class MyCheckoutVC: UIViewController { // ... func didTapBuyButton() { paymentSheetFlowController.confirm(from: self) { paymentResult in switch paymentResult { case .completed: // Payment completed - show a confirmation screen. case .failed(let error): // PaymentSheet encountered an unrecoverable error. You can display the error to the user, log it, etc. print(error) case .canceled: // Customer canceled - you should probably do nothing. } } } func handleConfirm(_ intentCreationCallback: @escaping (Result<String, Error>) -> Void) { // Make a request to your own server. let myServerResponse: Result<String, Error> = ... switch myServerResponse { case .success(let clientSecret): // Call the `intentCreationCallback` with the client secret intentCreationCallback(.success(clientSecret)) case .failure(let error): // Call the `intentCreationCallback` with the error intentCreationCallback(.failure(error)) } } }

The server code is explained in the following step.

Create a PaymentIntent
Server-side

On your server, create a PaymentIntent with an amount and currency. You can manage payment methods from the Dashboard. Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow. To prevent malicious customers from choosing their own prices, always decide how much to charge on the server-side (a trusted environment) and not the client.

If the call succeeds, return the PaymentIntent client secret. If the call fails, handle the error and return an error message with a brief explanation for your customer.

Note

Verify that all IntentConfiguration properties match your PaymentIntent (for example, setup_future_usage, amount, and currency).

main.rb
Ruby
require 'stripe' Stripe.api_key =
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
post '/create-intent' do data = JSON.parse request.body.read params = { amount: 1099, currency: 'usd', # In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default. automatic_payment_methods: {enabled: true}, } begin intent = Stripe::PaymentIntent.create(params) {client_secret: intent.client_secret}.to_json rescue Stripe::StripeError => e {error: e.error.message}.to_json end end

Handle post-payment events
Server-side

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard webhook tool or follow the webhook guide to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events is what enables you to accept different types of payment methods with a single integration.

In addition to handling the payment_intent.succeeded event, we recommend handling these other events when collecting payments with the Payment Element:

EventDescriptionAction
payment_intent.succeededSent when a customer successfully completes a payment.Send the customer an order confirmation and fulfill their order.
payment_intent.processingSent when a customer successfully initiates a payment, but the payment has yet to complete. This event is most commonly sent when the customer initiates a bank debit. It’s followed by either a payment_intent.succeeded or payment_intent.payment_failed event in the future.Send the customer an order confirmation that indicates their payment is pending. For digital goods, you might want to fulfill the order before waiting for payment to complete.
payment_intent.payment_failedSent when a customer attempts a payment, but the payment fails.If a payment transitions from processing to payment_failed, offer the customer another attempt to pay.

Test the integration

Card numberScenarioHow to test
The card payment succeeds and doesn’t require authentication.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The card payment requires authentication.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The card is declined with a decline code like insufficient_funds.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The UnionPay card has a variable length of 13-19 digits.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.

See Testing for additional information to test your integration.

OptionalEnable saved cards
Server-side
Client-side

OptionalAllow delayed payment methods
Client-side

OptionalEnable Apple Pay

OptionalEnable card scanning

OptionalCustomize the sheet

OptionalEnable CVC recollection on confirmation

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc