Get started with Flow for mobile

Last updated: October 15, 2025

Set up your client-side and server-side Flow integrations to enable payments in your mobile app.

The customer loads the checkout screen.
You perform a server-side request to create a payment session.
You use the payment session data on the client-side to create and render Flow for mobile.
Flow for mobile displays the available payment methods to the customer. If the customer's chosen payment method requires additional customer data, Flow captures this data from the customer.
When the customer taps Pay, Flow for mobile performs a payment request and handles any additional actions. For example, additional actions required for 3D Secure (3DS) authentication, or a third-party payment page redirect.
If the customer selected the option to save their card for faster checkout, we create a Remember Me profile for them and save their card to it. The customer can reuse their saved cards in future transactions.
You receive a webhook notifying you of the payment status.

Make sure you have a test account with Checkout.com.

Create a public key and a secret key from the Dashboard, with the following key scopes:

Public key – payment-sessions:pay and vault-tokenization
Secret key – payment-sessions

To receive webhooks for the payment events that can occur throughout the steps, set up your webhook receiver.

When the customer is ready to pay, send a server-side request to securely create a PaymentSession object. The PaymentSession contains the information required to handle all steps of the payment flow.

Note

Do not embed your secret key in your client-side code.

Call the Create a Payment Session endpoint.

Apple Pay and Google Pay are processed as card payments. The currency and billing.address.currency must be supported by:

Note

Apple Pay and Google Pay have additional requirements you must adhere to.

post

https://api.checkout.com/payment-sessions


1{
2 "amount": 1000,
3 "currency": "GBP",
4 "reference": "ORD-123A",
5 "billing": {
6   "address": {
7     "country": "GB"
8   }
9 },
10 "customer": {
11   "name": "Jia Tsang",
12   "email": "[email protected]"
13 },
14 "success_url": "https://example.com/payments/success",
15 "failure_url": "https://example.com/payments/failure"
16}


1{
2 "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
3 "payment_session_secret": "pss_e21237b4-214a-4e35-a35d-f33wkwo158f6"
4}

The payment session response determines which payment methods can be displayed to the customer. The response is determined by:

The customer's device
The customer's region
The payment methods that have been activated for your account – To activate additional payment methods on your account, contact your account manager or request support

Use Gradle to import the SDK into your app.

In your project-level build.gradle file, add:


1repositories {
2    mavenCentral()
3
4// Ensure the following Maven repositories are included, as they are specifically required for resolving Risk SDK dependencies:
5    maven { url = uri("https://jitpack.io") }
6    maven { url = uri("https://maven.fpregistry.io/releases") }
7}

In your app-level build.gradle file, add:


1dependencies {
2    implementation 'com.checkout:checkout-android-components:$latest_version'
3}

The client initializes an instance of CheckoutComponents with configuration information and the payment session data returned in the Create a Payment Session response.


1val configuration = CheckoutComponentConfiguration(
2context = context,
3paymentSession = PaymentSessionResponse(
4id = paymentSessionID,
5paymentSessionToken = paymentSessionToken,
6paymentSessionSecret = paymentSessionSecret,
7),
8publicKey = "YOUR_PUBLIC_KEY",
9environment = Environment.SANDBOX,
10)
11
12// Create CheckoutComponents
13CoroutineScope(Dispatchers.IO).launch {
14  try {
15    val checkoutComponents = CheckoutComponentsFactory(config = configuration).create()
16  } catch (checkoutError: CheckoutError) {
17    handleError(checkoutError)
18  }
19}

You can use the following configuration options to instantiate an instance of CheckoutComponents:

Key Description

Key	Description
`context` required	The Android content context.
`paymentSession` required	The response from the `PaymentSession`. This field is required to create and render the components that require a payment session.
`publicKey` required	Your public API key, prefixed with `pk_`.
`environment` required	Sets the environment that the library should point to and send requests to. Use: `SANDBOX` for your test environment `PRODUCTION` for your live environment
`locale`	Sets the customer's locale. Explicitly setting this value overrides the locale returned by the `PaymentSession`. For a list of supported languages, see Add localization to Flow for mobile.
`componentOptions`	Enables you to customize the options for the individual Flow components. For example, you can: Hide the pay button. Change the pay button mode to only tokenize the payment credentials. Append an address configuration for the address component that you can later embed in the card component. For customization options, see Component options.
`componentCallback`	Customizes the callbacks for the all Flow components. For customization options, see Customize Flow for mobile.
`translations`	Enables you to provide custom text translations for natively supported languages, or add custom text for locales and languages not natively supported by Flow for mobile. To learn how to add translations, see Add localization to Flow for mobile.
`appearance`	Enables you to customize the visual appearance of the `CheckoutAndroidComponents` elements. For customization options, see Customize Flow for mobile.
`flowCoordinator`	A map containing all the flow coordinators that add support for specific alternative payment methods (APMs). For example, `GooglePayFlowCoordinator` is required to integrate Google Pay.

context

required

The Android content context.

paymentSession

required

The response from the PaymentSession.

This field is required to create and render the components that require a payment session.

publicKey

required

Your public API key, prefixed with pk_.

environment

required

Sets the environment that the library should point to and send requests to. Use:

SANDBOX for your test environment
PRODUCTION for your live environment

locale

Sets the customer's locale. Explicitly setting this value overrides the locale returned by the PaymentSession.

For a list of supported languages, see Add localization to Flow for mobile.

componentOptions

Enables you to customize the options for the individual Flow components. For example, you can:

Hide the pay button.
Change the pay button mode to only tokenize the payment credentials.
Append an address configuration for the address component that you can later embed in the card component.

For customization options, see Component options.

componentCallback

Customizes the callbacks for the all Flow components.

For customization options, see Customize Flow for mobile.

translations

Enables you to provide custom text translations for natively supported languages, or add custom text for locales and languages not natively supported by Flow for mobile.

To learn how to add translations, see Add localization to Flow for mobile.

appearance

Enables you to customize the visual appearance of the CheckoutAndroidComponents elements.

For customization options, see Customize Flow for mobile.

flowCoordinator

A map containing all the flow coordinators that add support for specific alternative payment methods (APMs).

For example, GooglePayFlowCoordinator is required to integrate Google Pay.

Use CheckoutComponents to create a flow component that displays a list of all available payment methods for the current payment session:


1val flow = checkoutComponents.create(ComponentName.Flow)

flow contains a dynamic list of all of the payment methods available for the payment session you passed into CheckoutComponents.

Render Flow for mobile in Compose with render() or in a View container using provideView().


1checkoutComponent.Render();


1checkoutComponent.provideView(containerView)

Use SPM to import the SDK into your app.

In Xcode, go to Project > Package Dependencies, and add https://github.com/checkout/checkout-ios-components to your main target.

The client initializes an instance of CheckoutComponents with configuration information and the payment session data:


1let configuration = try await CheckoutComponents.Configuration(
2  paymentSession: paymentSession,
3  publicKey: publicKey,
4  environment: environment,
5  callbacks: .init(
6    onSuccess: { paymentMethod, paymentID in
7      // Handle success
8    },
9    onError: { error in
10      // Handle error
11    }
12  )
13)

Initialize the Flow for mobile payment component:


1try checkoutComponentsSDK.create(.flow()))

Check if the component is available, and render it:


1// First check if component is available
2if component.isAvailable {
3    return component.render()
4} else {
5    return nil
6}

You can use the following configuration options to instantiate an instance of CheckoutComponents:

Key Description

Key	Description
`paymentSession` required	The response from the `PaymentSession`. This field is required to create and render the components that require a payment session.
`publicKey` required	Your public API key, prefixed with `pk_`.
`environment` required	Sets the environment that the library points to and sends requests to. Use: `.sandbox` for your test environment `.production` for your live environment
`locale`	Sets the customer's locale. If you set this value at the SDK level, it overrides the locale returned in the `PaymentSession`. For a list of supported languages, see Add localization to Flow for mobile.
`callbacks`	Subscribes to the callbacks for all components. For the complete list of callbacks, see ComponentCallback.
`translations`	Enables you to provide custom text translations for natively supported languages, or add custom text for locales and languages that are not natively supported by Flow for mobile. To learn how to add translations, see add localization to Flow for mobile.
`appearance`	Enables you to customize the visual appearance of the components. To see the customization options, see Appearance options.

paymentSession

required

The response from the PaymentSession.

This field is required to create and render the components that require a payment session.

publicKey

required

Your public API key, prefixed with pk_.

environment

required

Sets the environment that the library points to and sends requests to. Use:

.sandbox for your test environment
.production for your live environment

locale

Sets the customer's locale.

If you set this value at the SDK level, it overrides the locale returned in the PaymentSession.

For a list of supported languages, see Add localization to Flow for mobile.

callbacks

Subscribes to the callbacks for all components.

For the complete list of callbacks, see ComponentCallback.

translations

Enables you to provide custom text translations for natively supported languages, or add custom text for locales and languages that are not natively supported by Flow for mobile.

To learn how to add translations, see add localization to Flow for mobile.

appearance

Enables you to customize the visual appearance of the components.

To see the customization options, see Appearance options.

You can use CheckoutComponents to render Flow for mobile in SwiftUI. Flow contains a dynamic list of all payment methods available for the payment session you passed in CheckoutComponents.

Use your preferred NodeJS package manager to import the package into your app.


1yarn add @checkout.com/checkout-react-native-components

Add the following to your settings.gradle file:


1dependencyResolutionManagement {
2  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
3  repositories {
4     google()
5     mavenCentral()
6     maven { url = uri("https://jitpack.io") }
7     maven { url = uri("https://maven.fpregistry.io/releases") }
8  }
9}


1cd ios
2pod install

Wrap the payment screen with the CheckoutProvider component and render Flow component:


1import {
2  CheckoutConfiguration,
3  CheckoutProvider,
4  Flow,
5} from '@checkout.com/checkout-react-native-components'
6
7export default function PaymentScreen() {
8  const config: CheckoutConfiguration = {
9    publicKey: 'pk_test',
10    environment: 'sandbox',
11  };
12
13  const onSuccess = (paymentMethod, paymentID) => {
14    console.log('Payment successful:', { paymentMethod, paymentID });
15  };
16
17  const onError = (error) => {
18    console.error('Payment error:', error);
19  };
20
21  return (
22    <CheckoutProvider
23      config={config}
24      onSuccess={onSuccess}
25      onError={onError}
26      paymentSession={paymentSession}
27    >
28      <Flow />
29    </CheckoutProvider>
30  )
31}

You can pass the following props to CheckoutProvider:

Key Description

Key	Description
`config` required	`CheckoutConfiguration` object required for providing the `environment` and `publicKey` values.
`paymentSession`	The response from `PaymentSession`. This field creates and renders the components that require a payment session.
`{...callbacks}`	For the complete list of callbacks, see Callbacks.

config

required

CheckoutConfiguration object required for providing the environment and publicKey values.

paymentSession

The response from PaymentSession.

This field creates and renders the components that require a payment session.

{...callbacks}

For the complete list of callbacks, see Callbacks.

Key	Description
`publicKey` required	Your public API key, prefixed with `pk_`.
`environment` required	Sets the environment that the library points and sends requests to. This can be one of: `production` `sandbox`
`locale`	Sets the customer's locale. If you set this value at the SDK level, it overrides the locale returned in the `PaymentSession`. For a list of supported languages, see Add localization to Flow for mobile.
`translations`	Enables you to provide custom text translations for natively supported languages, or add custom text for locales and languages that are not natively supported by Flow for mobile. To learn how to add translations, see Add localization to Flow for mobile.
`style`	Enables you to customize the visual appearance of the components. For the style options, see Customize Flow for mobile.
`merchantIdentifier`	Your Apple Pay merchant identifier (MID).

If you want to accept Apple Pay or Google Pay payments, follow these steps to add them to your Flow for mobile integration:

To implement Apple Pay in your mobile app, you must:

Create an Apple Merchant ID and a payment processing certificate.
Link your certificate to your merchant ID.
Add your Apple merchant ID to your iOS app.
Render the Apple Pay button in Flow for mobile.

Follow these steps:

In your Apple Developer account, select Merchant IDs to register for an Apple merchant ID. Use the suggested format: merchant.com.companyName.appName.
Depending on the environment where you want to update the certificate, run the following command to receive a certificate signing request from Checkout.com:


1curl --location --request POST 'https://api.checkout.com/applepay/signing-requests' \
2--header 'Authorization: Bearer pk_xxx' \
3| jq -r '.content' > ~/Desktop/cko.csr


1curl --location --request POST 'https://api.sandbox.checkout.com/applepay/signing-requests' \
2--header 'Authorization: Bearer pk_sbox_xxx' \
3| jq -r '.content' > ~/Desktop/cko.csr

The certificate downloads to your ~/Desktop path.

In your Apple Developer account, go to your merchant ID, and then go to Apple Pay Payment Processing Certificate > Create Certificate.
Upload the cko.csr certificate you created earlier, and select Continue.
Download the Apple Pay processing certificate you created.
On your terminal, go to the path where you downloaded Apple's processing certificate, and run the following command to upload it to Checkout.com's servers:


1curl --location --request POST 'https://api.checkout.com/applepay/certificates' \
2--header 'Authorization: Bearer pk_xxx' \
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "content": "'"$(openssl x509 -inform der -in apple_pay.cer | base64)"'"
6}'


1curl --location --request POST 'https://api.sandbox.checkout.com/applepay/certificates' \
2--header 'Authorization: Bearer pk_sbox_xxx' \
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "content": "'"$(openssl x509 -inform der -in apple_pay.cer | base64)"'"
6}'

Information

Ensure that the key you send in the Authorization header matches the environment you send the request to. For example, use your sandbox key for the request you send to the sandbox environment.

Go to your Apple Developer portal, and ensure that the certificate that you created is active.
You can manually activate it if not activated by default.
In Xcode, go to Targets > Signing & Capabilities, and add an Apple Pay capability.
Select the merchant ID you created earlier to use it with your app.
Render the Apple Pay button in your app by passing your Apple merchant ID in the options when rendering Flow for mobile's components:


1try checkoutComponentsSDK
2  .create(
3    .flow(options: [
4      .applePay(merchantIdentifier: "YOUR_MERCHANT_ID_HERE")
5      ]
6    )
7  )

For more information, see Apple Developer:

To implement Apple Pay in your React Native app, you must:

Create an Apple Merchant ID and a payment processing certificate.
Link your certificate to your merchant ID.
Add your Apple merchant ID to your iOS app.
Render the Apple Pay button in Flow for mobile.

Follow these steps:

In your Apple Developer account, select Merchant IDs to register for an Apple merchant ID. Use the suggested format: merchant.com.companyName.appName.
Depending on the environment where you want to update the certificate, run the following command to receive a certificate signing request from Checkout.com:


1curl --location --request POST 'https://api.checkout.com/applepay/signing-requests' \
2--header 'Authorization: Bearer pk_xxx' \
3| jq -r '.content' > ~/Desktop/cko.csr


1curl --location --request POST 'https://api.sandbox.checkout.com/applepay/signing-requests' \
2--header 'Authorization: Bearer pk_sbox_xxx' \
3| jq -r '.content' > ~/Desktop/cko.csr

The certificate downloads to your ~/Desktop path.

In your Apple Developer account, go to your merchant ID, and then go to Apple Pay Payment Processing Certificate > Create Certificate.
Upload the cko.csr certificate you created earlier, and select Continue.
Download the Apple Pay processing certificate you created.
On your terminal, go to the path where you downloaded Apple's processing certificate, and run the following command to upload it to Checkout.com's servers:


1curl --location --request POST 'https://api.checkout.com/applepay/certificates' \
2--header 'Authorization: Bearer pk_xxx' \
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "content": "'"$(openssl x509 -inform der -in apple_pay.cer | base64)"'"
6}'


1curl --location --request POST 'https://api.sandbox.checkout.com/applepay/certificates' \
2--header 'Authorization: Bearer pk_sbox_xxx' \
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "content": "'"$(openssl x509 -inform der -in apple_pay.cer | base64)"'"
6}'

Information

Ensure that the key you send in the Authorization header matches the environment you send the request to. For example, use your sandbox key for the request you send to the sandbox environment.

Go to your Apple Developer portal, and ensure that the certificate that you created is active.
You can manually activate it if it's not activated by default.
In Xcode, go to Targets > Signing & Capabilities, and add an Apple Pay capability.
Select the merchant ID you created earlier to use it with your app.
Add your Apple merchant ID to your configuration:


1const config: CheckoutConfiguration = {
2  publicKey: 'pk_test_your_key',
3  environment: 'sandbox',
4  merchantIdentifier: 'merchant.com.yourcompany.yourapp', // Your Apple merchant ID
5};

Render Apple Pay in Flow.


1import { CheckoutProvider, Flow } from '@checkout.com/checkout-react-native-components';
2
3<CheckoutProvider
4  config={config}
5  paymentSession={paymentSession}
6  onSuccess={onSuccess}
7  onError={onError}
8>
9  <Flow />
10</CheckoutProvider>

Apple Pay appears as a payment option when:

The device supports Apple Pay.
Your merchant ID is properly configured.

You can also render Apple Pay as a standalone component:


1import { CheckoutProvider, ApplePay } from '@checkout.com/checkout-react-native-components';
2
3<CheckoutProvider
4  config={config}
5  paymentSession={paymentSession}
6  onSuccess={onSuccess}
7  onError={onError}
8>
9 <ApplePay />
10</CheckoutProvider>

To accept Google Pay, you must include the GooglePayFlowCoordinator in the FlowCoordinator as shown in the following instructions:

Add the Google Pay API to your Android manifest file. In your AndroidManifest.xml, add the following meta-data tag within the <application> element:


1<application>
2   <!-- Other application configuration -->
3  
4   <meta-data
5       android:name="com.google.android.gms.wallet.api.enabled"
6       android:value="true" />
7      
8</application>

In the ViewModel class, create an lateinit variable of CheckoutComponents.
Create a function handleActivityResult to call the CheckoutComponents#handleActivityResult.
Expose handleActivityResult to the Activity and pass it in the GooglePayFlowCoordinator#handleActivityResult:


1lateinit var checkoutComponents: CheckoutComponents?
2
3fun handleActivityResult(resultCode: Int, data: String) {
4  checkoutComponents?.handleActivityResult(resultCode, data)
5}

In the Activity#onCreate method, create GooglePayFlowCoordinator with checkoutComponents.
Pass the viewModel#handleActivityResult in the GooglePayFlowCoordinator:


1val coordinator = GooglePayFlowCoordinator(
2    context = activity, // your activity context
3    handleActivityResult = { resultCode, data ->
4        viewModel.handleActivityResult(resultCode, data)
5    }
6)
7
8val flowCoordinators = mapOf(PaymentMethodName.GooglePay to coordinator)

In the ViewModel class, pass the flowCoordinators back to ViewModel.
Initiate CheckoutComponentConfiguration with flowCoordinators.
Initiate CheckoutComponentsFactory and CheckoutComponents.
Create a googlePayComponent variable and use it to render the component:


1val config = CheckoutComponentConfiguration(
2  context = context,
3  paymentSession = paymentSession,
4  publicKey = publicKey,
5  environment = environment,
6  flowCoordinators = flowCoordinators,
7)
8
9val checkoutComponents = CheckoutComponentsFactory(config).create()
10
11val googlePayComponent = checkoutComponents.create(PaymentMethodName.GooglePay)
12
13// Render it in a Composable function
14googlePayComponent.Render()
15
16// Render it in a View base function
17googlePayComponent.provideView(containerView)

To properly handle the lifecycle, the activity object that you pass in GooglePayFlowCoordinator must implement the following:

ViewModelStoreOwner
ActivityResultRegistryOwner
LifecycleOwner

If your activity object does not implement these interfaces, the creation of GooglePayFlowCoordinator fails, and the app throws an exception.

To implement Google Pay in your React Native app, you must:

Add the Google Pay API to your Android manifest file. In your AndroidManifest.xml, add the following meta-data tag within the <application> element:


1<!-- In android/app/src/main/AndroidManifest.xml -->
2<application>
3  <!-- Other application configuration -->
4
5  <meta-data
6    android:name="com.google.android.gms.wallet.api.enabled"
7    android:value="true" />
8    
9</application>

Render Google Pay in Flow:


1import { CheckoutProvider, Flow } from '@checkout.com/checkout-react-native-components';
2
3
4<CheckoutProvider
5  config={config}
6  paymentSession={paymentSession}
7  onSuccess={onSuccess}
8  onError={onError}
9>
10  <Flow />
11</CheckoutProvider>

Google Pay shows as a payment option when:

The device supports Google Pay.
Your Google Pay merchant account is properly configured.

You can also render Google Pay as a standalone component:


1import { CheckoutProvider, GooglePay } from '@checkout.com/checkout-react-native-components';
2
3
4<CheckoutProvider
5  config={config}
6  paymentSession={paymentSession}
7  onSuccess={onSuccess}
8  onError={onError}
9>
10  <GooglePay />
11</CheckoutProvider>

You can use Flow for mobile to handle payment methods that require a redirect (asynchronous payments) and those that do not (synchronous payments).

Depending on the payment outcome, some payment methods and 3D Secure authentication flows redirect the customer to a success or failure URL in your app.

We send you a webhook notifying you of changes to the payment's status. Wait for the webhook callback before you start your order fulfillment process.

For payments submitted with Flow, the PaymentSession ID is returned in the webhook payload's data.metadata.cko_payment_session_id field.

Optionally, you can retrieve the payment result from your server. Call the Get payment details endpoint, and provide the following:

{id} path parameter – The payment identifier
The cko-payment-id as a query parameter


1https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpasd

Payment methods that do not require a redirect raise an onSuccess event when the payment is successfully completed. You can use this to notify the customer of the payment status.

We send you a webhook notifying you of changes to the payment's status. Wait for the webhook callback before you start your order fulfillment process.


1val config = CheckoutComponentConfiguration(
2  paymentSession = paymentSession,
3  publicKey = publicKey,
4  environment = environment,
5  componentCallback = ComponentCallback(
6    onSuccess = { paymentMethodComponent, String ->
7    // Handle payment
8    }
9    onError = { paymentMethodComponent, checkoutError ->
10    // Handle error
11    }
12  )
13)


1let configuration = try await CheckoutComponents.Configuration(
2  paymentSession: paymentSession,
3  publicKey: publicKey,
4  environment: environment,
5  callbacks: .init(
6    onSuccess: { paymentMethod, paymentID in
7      // Handle success
8    },
9    onError: { error in
10      // Handle error
11    }
12  )
13)


1const config: CheckoutConfiguration = {
2  publicKey: 'pk_test_your_key',
3  environment: 'sandbox',
4};
5
6
7const onSuccess = (paymentMethod, paymentID) => {
8  // Handle successful payment
9};
10
11const onError = (error) => {
12  // Handle payment error
13};
14
15
16<CheckoutProvider
17  config={config}
18  paymentSession={paymentSession}
19  onSuccess={onSuccess}
20  onError={onError}
21>
22  <Flow />
23</CheckoutProvider>

Optionally, you can retrieve the payment result from your server by calling the Get payment details endpoint, providing the cko-payment-id path parameter. For example:


1https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpasd

Use test cards to simulate different payment flows and ensure your integration is set up correctly and behaving as expected.

Information

Ensure that you test every payment method that you plan to offer to your customers.

You can check the status of a payment from the Payments > Processing > All payments page in the Dashboard.

When you submit your Android app to Google Play, provide the required responses in your Data safety form.

Get started with Flow for mobile

Flow payment process

Before you begin

Create a Payment Session
Server side

Note

Note

Request example

Response example

Initialize and render Flow
Client side

Configuration options

Configuration options

CheckoutProvider props

CheckoutConfiguration object

Accept wallet payments
Optional

Apple Pay

Information

Information

Standalone Apple Pay Component

Google Pay

Standalone Google Pay Component

Handle the payment response
Client side

Synchronous payments

Test the integration

Information

Google Data safety form

Flow payment process

Before you begin

Create a Payment Session Server side

Note

Note

Request example

Response example

Initialize and render Flow Client side

Configuration options

Accept wallet payments Optional

Apple Pay

Information

Google Pay

Handle the payment response Client side

Synchronous payments

Test the integration

Information

Google Data safety form

Create a Payment Session
Server side

Initialize and render Flow
Client side

Accept wallet payments
Optional

Handle the payment response
Client side