# Get started with Flow for mobile Set up your client-side and server-side Flow integrations to enable payments in your mobile app. ## Flow payment process 1. The customer loads the checkout screen. 1. You perform a server-side request to create a payment session. 1. You use the payment session data on the client-side to create and render Flow for mobile. 1. 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. 1. 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)](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md) authentication, or a third-party payment page redirect. 1. If the customer selected the option to save their card for faster checkout, we create a [Remember Me](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/extend-your-flow-for-mobile-integration/enable-remember-me.md) profile for them and save their card to it. The customer can reuse their saved cards in future transactions. 1. You receive a webhook notifying you of the payment status. ![Diagram of the payment process when using Flow, showing the communication between your site, your server, and the Checkout.com server.](https://www.checkout.com/docs/large-media-assets/Flow-for-mobile-payment-process.png) --- ## Before you start Make sure you have a [test account](https://www.checkout.com/get-test-account) with Checkout.com. Create a [public key and a secret key](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) from the [Dashboard](https://dashboard.checkout.com), with the following key scopes: - Public key – `payment-sessions:pay` and `vault-tokenization` - Secret key – `payment-sessions` To receive webhooks for the [payment events](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway), [configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md). > **Information** > > Ensure you review the [Payment Card Industry Data Security Standard (PCI DSS) requirements](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app.md#PCI_DSS_requirements) for Flow for Mobile integrations. --- ## Create a Payment Session `Server side` 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](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession) endpoint. Apple Pay and Google Pay are processed as card payments. The `currency` and `billing.address.currency` must be supported by: - [Apple Pay](https://support.apple.com/en-gb/102775) - [Google Pay](https://support.google.com/googlepay/answer/12429287?hl=en-GB) > **Note** > > Apple Pay and Google Pay have [additional requirements](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app.md#Apple_Pay_and_Google_Pay_requirements) you must adhere to. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payment-sessions` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payment-sessions` ### Request example ```json { "amount": 1000, "currency": "GBP", "reference": "ORD-123A", "billing": { "address": { "country": "GB" } }, "customer": { "name": "Jia Tsang", "email": "jia.tsang@example.com" }, "success_url": "https://example.com/payments/success", "failure_url": "https://example.com/payments/failure" } ``` ### Response example ```json { "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ", "payment_session_secret": "pss_e21237b4-214a-4e35-a35d-f33wkwo158f6" } ``` 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](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes) --- ## Initialize and render Flow `Client side` **Android** Use Gradle to import the SDK into your app. In your project-level `build.gradle` file, add: ```gradle repositories { mavenCentral() // Ensure the following Maven repositories are included, as they are specifically required for resolving Risk SDK dependencies: maven { url = uri("https://jitpack.io") } maven { url = uri("https://maven.fpregistry.io/releases") } } ``` In your app-level `build.gradle` file, add: ```gradle dependencies { implementation 'com.checkout:checkout-android-components:$latest_version' } ``` The client initializes an instance of `CheckoutComponents` with configuration information and the payment session data returned in the Create a Payment Session response. ```kotlin val configuration = CheckoutComponentConfiguration( context = context, paymentSession = PaymentSessionResponse( id = paymentSessionID, paymentSessionToken = paymentSessionToken, paymentSessionSecret = paymentSessionSecret, ), publicKey = "YOUR_PUBLIC_KEY", environment = Environment.SANDBOX, ) // Create CheckoutComponents CoroutineScope(Dispatchers.IO).launch { try { val checkoutComponents = CheckoutComponentsFactory(config = configuration).create() } catch (checkoutError: CheckoutError) { handleError(checkoutError) } } ``` ### Configuration options You can use the following configuration options to instantiate an instance of `CheckoutComponents`: | 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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/add-localization-to-flow-for-mobile.md). | | `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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/checkoutwebcomponents.md). | | `componentCallback` | Customizes the callbacks for the all Flow components.

For customization options, see [Customize Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/customize-flow-for-mobile.md). | | `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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/add-localization-to-flow-for-mobile.md). | | `appearance` | Enables you to customize the visual appearance of the `CheckoutAndroidComponents` elements.

For customization options, see [Customize Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/customize-flow-for-mobile.md). | | `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: ```kotlin val 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()`. **Compose** ```kotlin checkoutComponent.Render(); ``` **View** ```kotlin checkoutComponent.provideView(containerView) ``` **iOS** Use SPM to import the SDK into your app. 1. 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: ```swift let configuration = try await CheckoutComponents.Configuration( paymentSession: paymentSession, publicKey: publicKey, environment: environment, callbacks: .init( onSuccess: { paymentMethod, paymentID in // Handle success }, onError: { error in // Handle error } ) ) ``` 2. Initialize the Flow for mobile payment component: ```swift try checkoutComponentsSDK.create(.flow())) ``` 3. Check if the component is available, and render it: ```swift // First check if component is available if component.isAvailable { return component.render() } else { return nil } ``` ### Configuration options You can use the following configuration options to instantiate an instance of `CheckoutComponents`: | 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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/add-localization-to-flow-for-mobile.md). | | `callbacks` | Subscribes to the callbacks for all components.

For the complete list of callbacks, see [ComponentCallback](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/ios/componentcallback.md). | | `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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/add-localization-to-flow-for-mobile.md). | | `appearance` | Enables you to customize the visual appearance of the components.

To see the customization options, see [Appearance options](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/customize-flow-for-mobile.md). | 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`. --- ## Accept wallet payments `Optional` If you want to accept Apple Pay or Google Pay payments, add them to your Flow for mobile integration: - [Add Apple Pay to Flow for mobile](https://www.checkout.com/docs/payments/add-payment-methods/apple-pay/ios.md) - [Add Google Pay to Flow for mobile](https://www.checkout.com/docs/payments/add-payment-methods/google-pay/android.md) --- ## Handle the payment response `Client side` 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](https://www.checkout.com/docs/payments/manage-payments/get-payment-details) endpoint, and provide the following: - `{id}` path parameter – The payment identifier - The `cko-payment-id` as a query parameter ``` https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpasd ``` ### Synchronous payments 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. **Android** ```kotlin val config = CheckoutComponentConfiguration( context = context, paymentSession = paymentSession, publicKey = publicKey, environment = environment, flowCoordinators = flowCoordinators, ) val checkoutComponents = CheckoutComponentsFactory(config).create() val googlePayComponent = checkoutComponents.create(PaymentMethodName.GooglePay) // Check if Google Pay is available val isAvailable = googlePayComponent.isAvailable() // Render it in a Composable function if(isAvailable) { googlePayComponent.Render() } // Render it in a View base function if(isAvailable) { googlePayComponent.provideView(containerView) } ``` **iOS** ```swift let configuration = try await CheckoutComponents.Configuration( paymentSession: paymentSession, publicKey: publicKey, environment: environment, callbacks: .init( onSuccess: { paymentMethod, paymentID in // Handle success }, onError: { error in // Handle error } ) ) ``` Optionally, you can retrieve the payment result from your server by calling the [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details) endpoint, providing the `cko-payment-id` path parameter. For example: ``` https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpasd ``` --- ## Test the integration Use [test cards](https://www.checkout.com/docs/developer-resources/testing/test-cards.md) 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](https://dashboard.checkout.com). ### Google Data safety form When you submit your Android app to Google Play, provide the [required responses](https://www.checkout.com/docs/developer-resources/sdks/data-safety-form.md) in your Data safety form.