Get started with Flow for mobile
Beta

Last updated: January 22, 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 "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_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
4"payment_session_secret": "pss_e21237b4-214a-4e35-a35d-f33wkwo158f6",
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 [email protected]

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(
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 = checkoutComponentConfiguration).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
`context`	The Android content context. This field is required.
`paymentSession`	The response from the `PaymentSession`. This field is required.
`publicKey`	Your public API key. Your key will be prefixed with `pk_`. This field is required.
`environment`	Sets the environment that the library should point to, and sends requests to. Use: `SANDBOX` for your test environment `PRODUCTION` for your live environment This field is required.
`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 change the position of the cardholder field 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.provideCheckoutComponentsLayout(containerView)

Use SPM to import the SDK into your app.

On Xcode, go to Project > Package Dependencies, and add: https://github.com/checkout/checkout-ios-components.
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.
`publicKey`	Your public API key, prefixed with `pk_`. This field is required.
`environment`	Sets the environment that the library points to, and sends requests to. Use: `SANDBOX` for your test environment `PRODUCTION` for your live environment This field is required.
`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.
`options`	Sets the specific properties that are available for the component. For example, you must pass the merchant ID for Apple Pay for the payment method to render.
`callbacks`	Customize the callbacks for the all Flow components. To see the customization options, refer to the component options documentation.
`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, refer to the add localization to Flow for mobile documentation.
`appearance`	Enables you to customize the visual appearance of the `CheckoutiOSComponents` elements. 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 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_sbox_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.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

Pass your production key in the Authorization header when sending the request to the Live 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.provide(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       }
11   )
12)


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 screen in the Dashboard.

Get started with Flow for mobile
Beta

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 mobile payment apps
Optional

Apple Pay

Information

Google Pay

Step 4: Handle the payment response
Client side

Synchronous payments

Test the integration

Information

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 mobile payment apps Optional

Apple Pay

Information

Google Pay

Step 4: Handle the payment response Client side

Synchronous payments

Test the integration

Information

Step 1: Create a new Payment Session
Server side

Step 2: Initialize and render Flow
Client side

Step 3: Accept mobile payment apps
Optional

Step 4: Handle the payment response
Client side