Accept in-app payments

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:

# Available as a gem
sudo gem install stripe

# 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:

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

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

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")

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.

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.

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

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.

The Embedded Mobile Payment Element is built for Jetpack Compose UI and exposes a @Composable Content method.

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.

import com.stripe.android.paymentelement.EmbeddedPaymentElement

@Composable
fun CheckoutScreen() {
    val embeddedBuilder = remember {
        EmbeddedPaymentElement.Builder(
            createIntentCallback = { _, _ ->
                TODO("Completed in a later step.")
            },
            resultCallback = { result ->
                TODO("Completed in a later 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-purpose 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.

@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

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

@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.

Update payment details

If the customer changes the payment details (for example, by applying a discount code), update the EmbeddedPaymentElement instance to reflect the new values by calling the configure method again. That synchronizes the values displayed in the UI.

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

val intentConfiguration = PaymentSheet.IntentConfiguration(
    mode = PaymentSheet.IntentConfiguration.Mode.Payment(
        amount = 2500,
        currency = "USD",
    ),
)

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

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

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.

When the request returns, 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.

val embeddedBuilder = remember {
    val embeddedBuilder = EmbeddedPaymentElement.Builder(
        createIntentCallback = { paymentMethod, shouldSavePaymentMethod ->
            val networkResult = ...
            when (networkResult) {
                is Result.Success -> {
                    CreateIntentResult.Success(networkResult.clientSecret)
                }
                is Result.Failure -> {
                    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, etc.
                }
                is EmbeddedPaymentElement.Result.Canceled -> {
                    // Customer canceled - you should probably do nothing.
                }
            }
        },
    )
}

(Optional) Display the selected payment option

If you want to display payment option details, such as the last 4, card logo, or billing information, access them through the EmbeddedPaymentElement’s paymentOption observable Flow property. When the customer selects a payment method that opens a form sheet, the payment option updates after they tap Continue in the sheet.

val selectedPaymentOption by embeddedPaymentElement.paymentOption.collectAsState()

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

    Text(text = selectedPaymentOption.label)
}

Confirm the PaymentIntent

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 click Call to action below the @Composable Content.

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

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:

See Testing for additional information to test your integration.