Accept in-app payments

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

The Payment Element is a customizable component that renders a list of payment methods that you can add into any screen in your app. When customers interact with payment methods in the list, the component opens individual bottom sheets to collect payment details.

Accounts v2 API support

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

iOS

Android

React Native

The Payment Element allows you to accept multiple payment methods using a single integration. In this integration, you build a custom payment flow where you render the Payment Element, create the PaymentIntent, and confirm the payment in your app.

Set up Stripe Server-side Client-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

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

# Available as a gem
sudo gem install stripe

Gemfile

Select a language

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

Select a language

Kotlin

Groovy

No results

plugins {
 id("com.android.application")
 id("org.jetbrains.kotlin.android")
 id("org.jetbrains.kotlin.plugin.compose")
}

android {
 ...
 kotlinOptions {
 jvmTarget = "11"
 }
 buildFeatures {
 compose true
 }
}

dependencies {
 // ...

 // Stripe Android SDK
 implementation("com.stripe:stripe-android:23.20.0")
 // Include the financial connections SDK to support US bank account as a payment method
 implementation("com.stripe:financial-connections:23.20.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 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.

Collect payment details Client-side

The Embedded Mobile Payment Element is designed for use on the checkout page of your native mobile app. The element displays a list of payment methods, and you can customize it to match your app’s look and feel.

When the customer taps the Card row, a sheet opens where they can enter their payment method details. The button in the sheet says Continue by default and dismisses the sheet when tapped, which lets your customer finish payment in your checkout.

Alternatively, you can configure the button to immediately complete payment instead of continuing. To do so, complete this step after following the guide.

Initialize the Embedded Payment Element

Initialize an instance of EmbeddedPaymentElement using the rememberEmbeddedPaymentElement function with an EmbeddedPaymentElement.Builder.

Pass in a CreateIntentWithConfirmationTokenCallback. For now, leave the implementation empty.

import com.stripe.android.paymentelement.EmbeddedPaymentElement
import com.stripe.android.paymentelement.rememberEmbeddedPaymentElement

@Composable
fun CheckoutScreen() {
 val embeddedBuilder = remember {
 EmbeddedPaymentElement.Builder(
 createIntentCallback = { confirmationToken, ->
 TODO("You'll implement this in the "Confirm the payment" step")
 },
 resultCallback = { result ->
 TODO("You'll implement this in the "Confirm the payment" step")
 },
 )
 }

 val embeddedPaymentElement = rememberEmbeddedPaymentElement(embeddedBuilder)
}

Configure the Embedded Payment Element

The Builder object contains callbacks necessary for instantiating EmbeddedPaymentElement, including the CreateIntentCallback. For now, leave its implementation empty.

After instantiating, call configure with an EmbeddedPaymentElement.Configuration and PaymentSheet.IntentConfiguration. The Configuration object contains general configuration options for EmbeddedPaymentElement that don’t change between payments. The IntentConfiguration object contains details about the specific payment, such as the amount and currency.

CheckoutScreen.kt

import com.stripe.android.paymentsheet.PaymentSheet

@Composable
fun CheckoutScreen() {
 val embeddedBuilder = ....
 val embeddedPaymentElement = rememberEmbeddedPaymentElement(embeddedBuilder)

 LaunchedEffect(embeddedPaymentElement) {
 embeddedPaymentElement.configure(
 intentConfiguration = PaymentSheet.IntentConfiguration(
 mode = PaymentSheet.IntentConfiguration.Mode.Payment(
 amount = 1099,
 currency = "USD",
 ),
 // Optional intent configuration options...
 ),
 configuration = EmbeddedPaymentElement.Configuration.Builder("Powdur").build()
 )
 }
}

Add the Embedded Payment Element view

After the EmbeddedPaymentElement has successfully initialized, put its @Composable Content in your checkout UI.

Note

The content must be in a scrollable container, because its height can change after it’s initially rendered.

CheckoutScreen.kt

@Composable
fun CheckoutScreen() {
 val embeddedBuilder = ....
 val embeddedPaymentElement = rememberEmbeddedPaymentElement(embeddedBuilder)

 .....

 val scrollState = rememberScrollState()

 Column(
 modifier = Modifier
 .fillMaxSize()
 .verticalScroll(scrollState)
 .padding(16.dp)
 ) {
 embeddedPaymentElement.Content()
 }
}

At this point, you can run your app and see the Embedded Mobile Payment Element.

Optional Update payment details

If a customer changes the payment details (for example, by applying a discount code), update the EmbeddedPaymentElement instance. When you call the configure method again, the new values synchronize and display in the UI.

Note

Some payment methods, like Google Pay, show the amount in the UI. If a customer changes the payment and you don’t update the EmbeddedPaymentElement, the UI displays incorrect values.

When the configure call completes, the @Composable Content and the paymentOption automatically update with the new values provided to the configure call.

CheckoutScreen.kt

val intentConfiguration = PaymentSheet.IntentConfiguration(
 // Update the amount to reflect the price after applying the discount code
 mode = PaymentSheet.IntentConfiguration.Mode.Payment(
 amount = 999,
 currency = "USD",
 ),
)

val configuration = EmbeddedPaymentElement.Configuration.Builder("Powdur")
 .build()

LaunchedEffect(embeddedPaymentElement) {
 embeddedPaymentElement.configure(
 intentConfiguration = intentConfiguration,
 configuration = configuration,
 )
}

Optional Display the selected payment option

You can display payment option details (such as the last 4 digits, a card logo, or billing information) by accessing the observable Flow property in the Embedded Payment Element’s paymentOption. When a customer selects a payment method that opens a form sheet, the payment option updates after they tap Continue in the sheet.

CheckoutScreen.kt

val selectedPaymentOption by embeddedPaymentElement.paymentOption.collectAsState()

selectedPaymentOption?.let { paymentOption ->
 Row(
 verticalAlignment = Alignment.CenterVertically,
 modifier = Modifier
 .clickable(
 onClick = { },
 )
 .semantics {
 text = AnnotatedString(paymentOption.label)
 },
 ) {
 Icon(
 painter = paymentOption.iconPainter,
 contentDescription = null, // decorative element
 modifier = Modifier.padding(horizontal = 4.dp),
 tint = Color.Unspecified,
 )

 Text(text = paymentOption.label)
 }
}

Confirm the payment

When the customer taps the checkout button, initiate the payment by calling embeddedPaymentElement.confirm(). Be sure to disable user interaction during confirmation.

When a form is presented, the EmbeddedPaymentElement calls confirm when the user clicks Call to action. If the selected payment method doesn’t have any form fields, call confirm when the user clicks Call to action below the @Composable Content.

CheckoutScreen.kt

Button(
 onClick = {
 embeddedPaymentElement.confirm()
 }
) {
 Text("Confirm payment")
}

Next, implement the createIntentCallback callback you passed to EmbeddedPaymentElement.Builder earlier to send a request to your server. Your server creates a PaymentIntent and returns its client secret, explained in Create a PaymentIntent.

When you receive the request, return the result of the Intent creation using CreateIntentResult with your server response’s client secret or an error. The EmbeddedPaymentElement confirms the PaymentIntent using the client secret or displays the localized error message in its UI.

CheckoutScreen.kt

import com.stripe.android.paymentsheet.CreateIntentResult

val embeddedBuilder = remember {
 val embeddedBuilder = EmbeddedPaymentElement.Builder(
 createIntentCallback = { confirmationToken ->
 // Make a request to your own server and receive a client secret or an error.
 val networkResult = ...
 if (networkResult.isSuccess) {
 CreateIntentResult.Success(networkResult.clientSecret)
 } else {
 CreateIntentResult.Failure(networkResult.exception)
 }
 },
 resultCallback = { result ->
 when (result) {
 is EmbeddedPaymentElement.Result.Completed -> {
 // Payment completed - show a confirmation screen.
 }
 is EmbeddedPaymentElement.Result.Failed -> {
 // Encountered an unrecoverable error. You can display the error to the user, log it, and so on
 }
 is EmbeddedPaymentElement.Result.Canceled -> {
 // Customer canceled - you should probably do nothing.
 }
 }
 },
 )
}

Optional Clear the selected payment option

Optional Display the mandate yourself

Optional Let the customer pay immediately in the sheet

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.

Set the same Customer or customer-configured Account on the PaymentIntent that you set on the CustomerSession.

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

Select a language

Ruby

Python

PHP

Node.js

Java

Go

.NET

No results

require 'stripe'
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('sk_test_BQokikJOvBiI2HlWgH4olfQ2')

post '/create-intent' do
 data = JSON.parse request.body.read
 params = {
 amount: 1099,
 currency: 'usd',
 automatic_payment_methods: {enabled: true},
 }
 begin
 intent = client.v1.payment_intents.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:

Test the integration

See Testing for additional information to test your integration.

Optional Enable saved cards Server-side Client-side

Optional Allow delayed payment methods Client-side

Optional Enable Google Pay

Optional Enable card scanning

Optional Customize the sheet

Optional Enable CVC recollection on confirmation