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
Payment methods
Payment operations
Balances and settlement timeReceiptsRefunds and cancellations
Advanced integrations
Beyond payments

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.

Compare Customers v1 and Accounts v2 references

If your Connect platform uses customer-configured Accounts, use our guide to replace Customer and event references in your code with the equivalent Accounts v2 API references.

A SetupIntent flow allows you to collect payment method details and save them for future payments without creating a charge. In this integration, you build a custom flow where you render the Payment Element, create the SetupIntent, and confirm saving the payment method in your app.

Set up Stripe
Server-sideClient-side

First, you need a Stripe account. Register now.

Server-side

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

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Client-side

The Stripe Android SDK is open source and fully documented.

To install the SDK, add stripe-android to the dependencies block of your app/build.gradle file:

build.gradle.kts
Kotlin
Groovy
No results
plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:22.8.0")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:22.8.0")
}

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 quickly, you can hardcode this 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
PaymentConfiguration.init(context, 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 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.

Create a Customer
Server-side

To set up a payment method for future payments, you must attach it to a Customer. Create a Customer object when your customer creates an account with your business. Customer objects allow for reusing payment methods and tracking across multiple payments.

Compare Customers v1 and Accounts v2 references

If your Connect platform uses customer-configured Accounts, use our guide to replace Customer and event references in your code with the equivalent Accounts v2 API references.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Collect payment details
Client-side

We offer two styles of integration.

PaymentSheet PaymentSheet.FlowController
PaymentSheet
PaymentSheet.FlowController
Displays a sheet to collect and save payment details. The button label is Set up. Clicking it saves the payment details. Displays a sheet to only collect payment details. The button label is Continue. Clicking it returns the customer to your app, where your own button saves the payment details.

Initialize the PaymentSheet

Initialize the PaymentSheet and pass in a CreateIntentCallback. Leave the implementations empty for now.

class MyCheckoutActivity : AppCompatActivity() {

  private lateinit var paymentSheet: PaymentSheet

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...

    paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult)
      .createIntentCallback { confirmationToken ->
        TODO() // You'll implement this later
      }
      .build(this)
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    // You'll implement this later
  }
}

Present the PaymentSheet

Next, present the PaymentSheet by calling presentWithIntentConfiguration() and pass in an IntentConfiguration. The IntentConfiguration contains details about the specific SetupIntent, such as the currency.

class MyCheckoutActivity : AppCompatActivity() {

  // ...

  private fun handleCheckoutButtonPressed() {
    val intentConfig = PaymentSheet.IntentConfiguration(
      mode = PaymentSheet.IntentConfiguration.Mode.Setup(
        currency = "usd",
      ),
      // Other configuration options...
    )

    paymentSheet.presentWithIntentConfiguration(
      intentConfiguration = intentConfig,
      // Optional configuration - See the "Customize the sheet" section in this guide
      configuration = PaymentSheet.Configuration.Builder(
        merchantDisplayName = "Example Inc.",
      ).build()
    )
  }
}

Confirm the Intent

When your customer taps the Setup button in PaymentSheet, it calls the CreateIntentCallback you passed above with a ConfirmationToken that represents your customer’s payment details and preferences.

Implement this method to send a request to your server with confirmationToken.id. Your server creates a SetupIntent and returns its client secret.

When you receive the response, return the response’s client secret or an error. The PaymentSheet confirms the SetupIntent using the client secret, or displays the error in its UI.

class MyCheckoutActivity : AppCompatActivity() {

  private lateinit var paymentSheet: PaymentSheet

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...

    paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult)
      .createIntentCallback { confirmationToken ->
        // Make a request to your server to create a SetupIntent and return its client secret
        val networkResult = myNetworkClient.createIntent(
          confirmationTokenId = confirmationToken.id,
        )
        if (networkResult.isSuccess) {
            CreateIntentResult.Success(networkResult.clientSecret)
        } else {
            CreateIntentResult.Failure(networkResult.exception)
        }
      }
      .build(this)
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    // You'll implement this later
  }
}

After your customer saves a payment method, the sheet closes, and PaymentSheet invokes the PaymentSheetResultCallback you provide with a PaymentSheetResult.

class MyCheckoutActivity : AppCompatActivity() {

  // ...

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    when(paymentSheetResult) {
      is PaymentSheetResult.Canceled -> {
        // Customer canceled - you should probably do nothing.
      }
      is PaymentSheetResult.Failed -> {
        print("Error: ${paymentSheetResult.error}")
        // PaymentSheet encountered an unrecoverable error. You can display the error to the user, log it, and so on
      }
      is PaymentSheetResult.Completed -> {
        // Display, for example, an order confirmation screen
        print("Completed")
      }
    }
  }
}

Create a SetupIntent
Server-side

On your server, create a SetupIntent. You can manage payment methods from the Dashboard. Stripe evaluates payment method restrictions and other parameters to determine the list of supported payment methods.

If the call succeeds, return the SetupIntent 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 SetupIntent (for example, usage).

main.rb
Ruby
Python
PHP
Node.js
Java
Go
.NET
No results
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


post '/create-intent' do
  data = JSON.parse request.body.read
  params = {
    customer: ..., # The Customer ID you previously created
    # 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::SetupIntent.create(params)
    {client_secret: intent.client_secret}.to_json
  rescue Stripe::StripeError => e
    {error: e.error.message}.to_json
  end
end

Charge the saved payment method later
Server-side

Warning

bancontact and ideal are one-time payment methods by default. When set up for future usage, they generate a sepa_debit reusable payment method type so you need to use sepa_debit to query for saved payment methods.

Compliance

You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer’s payment details. When rendering past payment methods to your end customer for future purchases, make sure you’re listing payment methods where you’ve collected consent from the customer to save the payment method details for this specific future use. To differentiate between payment methods attached to customers that can and can’t be presented to your end customer as a saved payment method for future purchases, use the allow_redisplay parameter.

When you’re ready to charge your customer off-session, use the Customer and PaymentMethod IDs to create a PaymentIntent. To find a payment method to charge, list the payment methods associated with your customer. This example lists cards but you can list any supported type.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -G https://api.stripe.com/v1/payment_methods \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
"{{CUSTOMER_ID}}"
 \
  -d type=card

When you have the Customer and PaymentMethod IDs, create a PaymentIntent with the amount and currency of the payment. Set a few other parameters to make the off-session payment:

  • Set off_session to true to indicate that the customer isn’t in your checkout flow during a payment attempt and can’t fulfill an authentication request made by a partner, such as a card issuer, bank, or other payment institution. If, during your checkout flow, a partner requests authentication, Stripe requests exemptions using customer information from a previous on-session transaction. If the conditions for exemption aren’t met, the PaymentIntent might throw an error.
  • Set the value of the PaymentIntent’s confirm property to true, which causes confirmation to occur immediately when the PaymentIntent is created.
  • Set payment_method to the ID of the PaymentMethod and customer to the ID of the Customer.
Command Line
curl
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d amount=1099 \
  -d currency=usd \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d customer="{{CUSTOMER_ID}}" \
  -d payment_method="{{PAYMENT_METHOD_ID}}" \
  -d return_url="https://example.com/order/123/complete" \
  -d off_session=true \
  -d confirm=true

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-sideClient-side

PaymentSheet can allow the customer to save their card and can include the customer’s saved cards in available payment methods. The customer must have an associated Customer object on your server. To enable a checkbox that allows the customer to save their card, create a CustomerSession, with payment_method_save set to enabled.

app.js
const stripe = require("stripe")(
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
const express = require('express');
const app = express();

app.set('trust proxy', true);
app.use(express.json());

app.post('/payment-sheet', async (req, res) => {
  // Use an existing Customer ID if this is a returning customer.
  const customer = await stripe.customers.create();
  const customerSession = await stripe.customerSessions.create({
    customer: customer.id,
    components: {
      mobile_payment_element: {
        enabled: true,
        features: {
          payment_method_save: 'enabled',
          payment_method_redisplay: 'enabled',
          payment_method_remove: 'enabled'
        }
      },
    },
  });

  res.json({
    customerSessionClientSecret: customerSession.client_secret,
    customer: customer.id,
  });
});

Next, present PaymentSheet with the Customer’s ID and the CustomerSession client secret.

val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Powdur")
  .customer(
      PaymentSheet.CustomerConfiguration.createWithCustomerSession(
          id = customerId,
          clientSecret = customerSessionClientSecret,
      )
  )
  .build()

paymentSheet.presentWithIntentConfiguration(
    intentConfiguration = // ... ,
    configuration = configuration,
)

OptionalAllow delayed payment methods
Client-side

Delayed payment methods don’t guarantee that you’ll receive funds from your customer at the end of checkout, either because they take time to settle (for example, US Bank Accounts, SEPA Debit, iDEAL, Bancontact, and Sofort) or because they require customer action to complete (for example, OXXO, Konbini, and Boleto).

By default, PaymentSheet doesn’t display delayed payment methods. To include the delayed payment methods that PaymentSheet supports, set allowsDelayedPaymentMethods to true in your PaymentSheet.Configuration.

val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Powdur")
  .allowsDelayedPaymentMethods(true)
  .build()

If the customer successfully uses a delayed payment method in a PaymentSheet, the payment result returned is PaymentSheetResult.Completed.

OptionalEnable Google Pay

Note

If your checkout screen has a dedicated Google Pay button, follow the Google Pay guide. You can use Embedded Payment Element to handle other payment method types.

Set up your integration

To use Google Pay, first enable the Google Pay API by adding the following to the <application> tag of your AndroidManifest.xml:

AndroidManifest.xml
<application>
  ...
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>

For more details, see Google Pay’s Set up Google Pay API for Android.

Add Google Pay

To add Google Pay to your integration, pass a PaymentSheet.GooglePayConfiguration with your Google Pay environment (production or test) and the country code of your business when initializing PaymentSheet.Configuration.

Kotlin
Java
No results
val googlePayConfiguration = PaymentSheet.GooglePayConfiguration(
  environment = PaymentSheet.GooglePayConfiguration.Environment.Test,
  countryCode = "US",
  currencyCode = "USD" // Required for Setup Intents, optional for Payment Intents
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
  .googlePay(googlePayConfiguration)
  .build()

Test Google Pay

Google allows you to make test payments through their Test card suite. The test suite supports using Stripe test cards.

You must test Google Pay using a physical Android device instead of a simulated device, in a country where Google Pay is supported. Log in to a Google account on your test device with a real card saved to Google Wallet.

OptionalEnable card scanning

To enable card scanning support, request production access to the Google Pay API from the Google Pay and Wallet Console.

  • If you’ve enabled Google Pay, the card scanning feature is automatically available in our UI on eligible devices. To learn more about eligible devices, see the Google Pay API constraints
  • Important: The card scanning feature only appears in builds signed with the same signing key registered in the Google Pay & Wallet Console. Test or debug builds using different signing keys (for example, builds distributed through Firebase App Tester) won’t show the Scan card option. To test card scanning in pre-release builds, you must either:
    • Sign your test builds with your production signing key
    • Add your test signing key fingerprint to the Google Pay and Wallet Console

OptionalCustomize the sheet

All customization is configured using the PaymentSheet.Configuration object.

Appearance

Customize colors, fonts, and more to match the look and feel of your app by using the appearance API.

Payment method layout

Configure the layout of payment methods in the sheet using paymentMethodLayout. You can display them horizontally, vertically, or let Stripe optimize the layout automatically.

Kotlin
Java
No results
PaymentSheet.Configuration.Builder("Example, Inc.")
  .paymentMethodLayout(PaymentSheet.PaymentMethodLayout.Automatic)
  .build()

Collect users addresses

Collect local and international shipping or billing addresses from your customers using the Address Element.

Business display name

Specify a customer-facing business name by setting merchantDisplayName. By default, this is your app’s name.

Kotlin
Java
No results
PaymentSheet.Configuration.Builder(
  merchantDisplayName = "My app, Inc."
).build()

Dark mode

By default, PaymentSheet automatically adapts to the user’s system-wide appearance settings (light and dark mode). You can change this by setting light or dark mode on your app:

Kotlin
Java
No results
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)

Default billing details

To set default values for billing details collected in the payment sheet, configure the defaultBillingDetails property. The PaymentSheet pre-populates its fields with the values that you provide.

Kotlin
Java
No results
val address = PaymentSheet.Address(country = "US")
val billingDetails = PaymentSheet.BillingDetails(
  address = address,
  email = "foo@bar.com"
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
  .defaultBillingDetails(billingDetails)
  .build()

Configure collection of billing details

Use BillingDetailsCollectionConfiguration to specify how you want to collect billing details in the PaymentSheet.

You can collect your customer’s name, email, phone number, and address.

If you want to attach default billing details to the PaymentMethod object even when those fields aren’t collected in the UI, set billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod to true.

Kotlin
Java
No results
val billingDetails = PaymentSheet.BillingDetails(
  email = "foo@bar.com"
)
val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration(
  attachDefaultsToPaymentMethod = true,
  name = BillingDetailsCollectionConfiguration.CollectionMode.Always,
  email = BillingDetailsCollectionConfiguration.CollectionMode.Never,
  address = BillingDetailsCollectionConfiguration.AddressCollectionMode.Full,
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
  .defaultBillingDetails(billingDetails)
  .billingDetailsCollectionConfiguration(billingDetailsCollectionConfiguration)
  .build()

Note

Consult with your legal counsel regarding laws that apply to collecting information. Only collect phone numbers if you need them for the transaction.