Get started with Flow for mobile

Last updated: August 13, 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 the Pay button, 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.
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 notifications for the payment events that may be triggered throughout the steps, configure your webhook receiver.

When the customer is ready to pay, you must 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.

Information

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

To create a new PaymentSession, call the following endpoint with your secret key:

post

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

For the full API specification, see the API reference.


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


1{
2  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
3  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
4  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
5  "_links": {
6    "self": {
7      "href": "https://api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
8    }
9  }
10}

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 enable additional payment methods on your account, contact your account manager or request support

Some payment methods may require you to provide additional fields or specific values.

Information

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

Payment method	Field requirements
Card payments	No additional requirements.
Apple Pay	Apple Pay is processed as a card transaction `currency` and `billing.address.country` must be supported by Apple Pay
Google Pay	Google Pay is processed as a card transaction `currency` and `billing.address.country` must be supported by Google Pay

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 retrieved in step 1.


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

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

Key	Description
`context`	The Android content context. This field is required.
`paymentSession`	The response from the `PaymentSession`. This field is required to create and render the components that require a payment session.
`publicKey`	Your public API key. Your key will be prefixed with `pk_`. This field is required.
`environment` required	Sets the environment that the library should point to, and sends requests to. This can be one of: `PRODUCTION` `SANDBOX`
`locale`	Sets the customer's locale. Explicitly setting this value will override 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 To see the customization options, refer to the component options documentation.
`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. To see the customization options, refer to the appearance options documentation.
`flowCoordinator`	A map containing all the flow coordinators that add support for specific 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
`paymentSession`	The response from the `PaymentSession`. This field is required to create and render the components that require a payment session.
`publicKey`	Your public API key, prefixed with `pk_`. This field is required.
`environment` required	Sets the environment that the library points to, 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.
`callbacks`	Subscribes to the callbacks for all the 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, refer to the add localization to Flow for mobile documentation.
`appearance`	Enables you to customize the visual appearance of the components. To see the customization options, refer to the appearance options documentation.

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

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 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.
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 the following Apple documentation:

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

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

ViewModelStoreOwner
ActivityResultRegistryOwner
LifecycleOwner

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

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.

A webhook is sent to your server notifying you of changes to the payment's status. Wait for the webhook callback before you trigger 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 – for example:


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

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

A webhook is sent to your server notifying you of changes to the payment's status. Wait for the webhook callback before you trigger 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)

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 our test cards to simulate different payment flows, to ensure your integration is set up correctly and behaving as expected.

Information

Ensure that you test each 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 start

Step 1: Create a new Payment Session
Server side

Information

Request example

Response example

Payment method field requirements

Information

Step 2: Initialize and render Flow
Client side

Configuration options

Configuration options

Step 3: Accept wallet payments
Optional

Apple Pay

Information

Google Pay

Step 4: Handle the payment response
Client side

Synchronous payments

Test the integration

Information

Google Data safety form

Flow payment process

Before you start

Step 1: Create a new Payment Session Server side

Information

Request example

Response example

Payment method field requirements

Information

Step 2: Initialize and render Flow Client side

Configuration options

Step 3: Accept wallet payments Optional

Apple Pay

Information

Google Pay

Step 4: Handle the payment response Client side

Synchronous payments

Test the integration

Information

Google Data safety form

Step 1: Create a new Payment Session
Server side

Step 2: Initialize and render Flow
Client side

Step 3: Accept wallet payments
Optional

Step 4: Handle the payment response
Client side