Upgrade from Frames for Android

Last updated: March 12, 2025

Follow this guide to upgrade your Frames for Android integration to Flow for mobile.

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.

To prepare for the upgrade to Flow, remove all Frames code from your client-side and server-side integrations.

Remove Frames from the Gradle file of the app.


1// app gradle file
2implementation("com.github.checkout:frames-android:<latest_version>")

Remove any Kotlin code where you initialize Frames. For example:


1val paymentFlowHandler = PaymentFlowHandler()
2val paymentFormConfig = PaymentFormConfig(
3    publicKey = PUBLIC_KEY,
4    context = context,       
5    environment = Environment.Production,   
6    paymentFlowHandler = paymentFlowHandler,
7    style = PaymentFormStyle(),
8)
9val paymentFormMediator = PaymentFormMediator(paymentFormConfig())
10
11// in Activity
12paymentFormMediator.setActivityContent(activity)
13
14// in Compose
15paymentFormMediator.PaymentForm()

Remove all server-side API calls to the following endpoints:

post

https://api.checkout.com/payments

Update your server to create a PaymentSession for the Flow integration:


1const createPaymentSession = async (req, res) => {
2  const response = await fetch("https://api.checkout.com/payment-sessions", {
3    method: "POST",
4    headers: {
5      Authorization: `Bearer ${secretKey}`,
6      "Content-Type": "application/json",
7    },
8    body: JSON.stringify({
9      amount: 1000,
10      currency: "GBP",
11      reference: "ORD-123A",
12      display_name: "Online Shop",
13      billing: {
14        address: { country: "GB" },
15      },
16      customer: {
17        name: "Jia Tsang",
18        email: "[email protected]",
19      },
20      success_url: "https://example.com/payments/success",
21      failure_url: "https://example.com/payments/failure",
22    }),
23  });
24
25  const paymentSession = await response.json();
26  res.json(paymentSession);
27};

Include the Flow dependency in your app:


1// app gradle file
2implementation("com.checkout:checkout-android-components:<latest_version>")
3
4// project gradle file
5repositories {
6    mavenCentral()
7}

Configure Flow with your public key and the payment session data returned from the server:


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

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)

Add the Flow component to a container View or render Flow in a Composable function:


1// in Compose
2if (flow.isAvailable) {
3    flow.Render()
4}
5
6// in View
7if (flow.isAvailable) {
8    flow.provideView(containerView)
9}

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

Depending on the payment outcome, customers are redirected to the success_url or failure_url you specified when you created the PaymentSession.

We send a webhook 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 using the callbacks provided by Flow:

onSuccess for successful payments
onError for unsuccessful payments

For payment methods that do not require a redirect, use the onSuccess callback to handle payments. You can use this to notify the customer of the payment status.


1val config = CheckoutComponentConfiguration(
2    context = context,
3    paymentSession = paymentSessionResponse,
4    publicKey = PUBLIC_KEY,
5    environment = Environment.PRODUCTION,
6    componentCallback = ComponentCallback(
7        onSuccess = { component, paymentId ->
8            // Complete order in server side
9            completeOrder(paymentId);
10         }
11    )
12)

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.

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.

You can use Flow for mobile to natively offer Google Pay payments.

To upgrade from your Google Pay Frames integration:

Contact your account manager and provide your Google Pay Merchant ID.
Remove the Google Pay SDK integration from your Gradle files.
Remove any Google Pay SDK code from your app.
Remove any GooglePayTokenRequest related code from your Frames implementation. For Example:


1val checkoutApiClient = CheckoutApiServiceFactory.create(
2    publicKey = PUBLIC_KEY,
3    environment = Environment.PRODUCTION,
4    context = context,
5)
6
7val request = GooglePayTokenRequest(
8    tokenJsonPayload = tokenJsonPayload,
9    onSuccess = { tokenDetails ->
10       /* Handle success result */
11        tokenDetails.token
12    },
13    onFailure = { errorMessage ->
14        /* Handle failure result */
15    },
16)
17checkoutApiClient.createToken(request)

Follow the Flow for mobile instructions to accept Google Pay payments.

Upgrade from Frames for Android

Before you start

Remove existing Frames code

Remove Frames dependency
Client side

Remove Frames initialization
Client side

Remove payment logic
Server side

Create a Flow Payment Session
Server side

Initialize and mount Flow
Client side

Add Flow dependency

Initialize Flow

Render Flow

Handle payment responses

Asynchronous payments

Synchronous payments

Test the Flow integration

Information

Upgrade your Google Pay integration

Next steps

Customize your Flow for mobile integration

Flow for mobile library reference

Tokenize credentials

Before you start

Remove existing Frames code

Remove Frames dependency Client side

Remove Frames initialization Client side

Remove payment logic Server side

Create a Flow Payment Session Server side

Initialize and mount Flow Client side

Add Flow dependency

Initialize Flow

Render Flow

Handle payment responses

Asynchronous payments

Synchronous payments

Test the Flow integration

Information

Upgrade your Google Pay integration

Next steps

Customize your Flow for mobile integration

Flow for mobile library reference

Tokenize credentials

Remove Frames dependency
Client side

Remove Frames initialization
Client side

Remove payment logic
Server side

Create a Flow Payment Session
Server side

Initialize and mount Flow
Client side