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
andvault-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 {2mavenCentral()34// Ensure the following Maven repositories are included, as they are specifically required for resolving Risk SDK dependencies:5maven { url = uri("https://jitpack.io") }6maven { url = uri("https://maven.fpregistry.io/releases") }7}
In your app-level build.gradle
file, add:
1dependencies {2implementation '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)1112// Create CheckoutComponents13CoroutineScope(Dispatchers.IO).launch {14try {15val checkoutComponents = CheckoutComponentsFactory(config = configuration).create()16} catch (checkoutError: CheckoutError) {17handleError(checkoutError)18}19}
You can use the following configuration options to instantiate an instance of CheckoutComponents
:
Key | Description |
---|---|
required | The Android content context. |
required | The response from the This field is required to create and render the components that require a payment session. |
required | Your public API key, prefixed with |
required | Sets the environment that the library should point to and send requests to. Use:
|
| Sets the customer's locale. Explicitly setting this value overrides the locale returned by the For a list of supported languages, see Add localization to Flow for mobile. |
| Enables you to customize the options for the individual Flow components. For example, you can:
For customization options, see Component options. |
| Customizes the callbacks for the all Flow components. For customization options, see Customize Flow for mobile. |
| 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. |
| Enables you to customize the visual appearance of the For customization options, see Customize Flow for mobile. |
| A map containing all the flow coordinators that add support for specific alternative payment methods (APMs). For example, |
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();
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
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}'
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 checkoutComponentsSDK2.create(3.flow(options: [4.applePay(merchantIdentifier: "YOUR_MERCHANT_ID_HERE")5]6)7)
For more information, see Apple Developer:
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 -->34<meta-data5android:name="com.google.android.gms.wallet.api.enabled"6android:value="true" />78</application>
- In the
ViewModel
class, create anlateinit
variable ofCheckoutComponents
. - Create a function
handleActivityResult
to call theCheckoutComponents#handleActivityResult
. - Expose
handleActivityResult
to the Activity and pass it in theGooglePayFlowCoordinator#handleActivityResult
:
1lateinit var checkoutComponents: CheckoutComponents?23fun handleActivityResult(resultCode: Int, data: String) {4checkoutComponents?.handleActivityResult(resultCode, data)5}
- In the
Activity#onCreate
method, createGooglePayFlowCoordinator
withcheckoutComponents
. - Pass the
viewModel#handleActivityResult
in theGooglePayFlowCoordinator
:
1val coordinator = GooglePayFlowCoordinator(2context = activity, // your activity context3handleActivityResult = { resultCode, data ->4viewModel.handleActivityResult(resultCode, data)5}6)78val flowCoordinators = mapOf(PaymentMethodName.GooglePay to coordinator)
- In the
ViewModel
class, pass theflowCoordinators
back toViewModel
. - Initiate
CheckoutComponentConfiguration
withflowCoordinators
. - Initiate
CheckoutComponentsFactory
andCheckoutComponents
. - Create a
googlePayComponent
variable and use it to render the component:
1val config = CheckoutComponentConfiguration(2context = context,3paymentSession = paymentSession,4publicKey = publicKey,5environment = environment,6flowCoordinators = flowCoordinators,7)89val checkoutComponents = CheckoutComponentsFactory(config).create()1011val googlePayComponent = checkoutComponents.create(PaymentMethodName.GooglePay)1213// Render it in a Composable function14googlePayComponent.Render()1516// Render it in a View base function17googlePayComponent.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.
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(2paymentSession = paymentSession,3publicKey = publicKey,4environment = environment,5componentCallback = ComponentCallback(6onSuccess = { paymentMethodComponent, String ->7// Handle payment8}9onError = { paymentMethodComponent, checkoutError ->10// Handle error11}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 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.