Tamara for mobile app

Last updated: June 3, 2026

Accept Tamara payments on your app with Flow for mobile, our pre-built, customizable payment user interface that you can embed directly into your mobile application. Flow enables you to accept payments using Checkout.com's global network of payment methods with a single integration.

The customer opens the checkout screen.
When you load the page, 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 the data from the customer.
When the customer taps Pay, Flow for mobile performs a payment request and handles any additional actions required. For example, third-party payment page redirects.
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 webhooks for the payment events, configure your webhook server.

Integrate with Flow for mobile before continuing.

Ensure your merchant account has Tamara enabled. To enable Tamara, contact your account manager or request support.

In your project-level build.gradle, add the following repositories:


1repositories {
2    mavenCentral()
3    maven { url = uri("https://jitpack.io") }
4    maven { url = uri("https://maven.fpregistry.io/releases") }
5}

In your app-level build.gradle, add the following dependency:


1dependencies {
2    implementation 'com.checkout:checkout-android-components:$latest_version'
3    implementation('com.checkout:checkout-android-components-payment-methods-redirect:$latest_version')
4}

To add payment methods to your iOS app, enable the CheckoutPaymentMethods plugin.

If you have already added the checkout-ios-components package:

In Xcode, select your project, then select the Package Dependencies tab.
Find checkout-ios-components and select the pencil icon to edit it.
Select CheckoutPaymentMethods in the product list and confirm.

If you are adding the package for the first time:

Select File > Add Package Dependencies.
Enter the checkout-ios-components repository URL.
Select both CheckoutComponents and CheckoutPaymentMethods from the product list.
Select Add Package.

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.

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.

post

https://{prefix}.api.checkout.com/payment-sessions


1{
2  "amount": 1000,
3  "currency": "AED",
4  "reference": "ORDER_01234",
5  "billing": {
6    "address": {
7      "country": "AE"
8    }
9  },
10  "customer": {
11    "name": "Jia Tsang",
12    "email": "jia.tsang@example.com"
13  },
14  "success_url": "https://example.com/payments/success",
15  "failure_url": "https://example.com/payments/failure"
16}

In the request body, provide the following:

Field	Description
`currency`	The three-letter ISO 4217 currency code. Must be one of: `SAR` `AED` `KWD`. Required
`customer.name`	The customer's name. Required
`customer.email`	The customer's email address. Required
`billing.address`	The customer's billing address. Required
`billing.phone`	The customer's billing phone number, required for KSA compliance. Required
`shipping.address`	The customer's shipping address. Required
`shipping.phone`	The customer's shipping phone number. Required
`reference`	A reference shown to the customer in the Tamara checkout page.
`description`	The description of the order.
`items`	Items to show in the Tamara checkout page.


1{
2  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
3  "payment_session_secret": "pss_e21237b4-214a-4e35-a35d-f33wkwo158f6"
4}

The payment session response also determines which payment methods can be displayed to the customer. The response is determined by the customer's device and region.

Enable Tamara in Flow for mobile when creating a CheckoutComponents instance.

Pass Tamara.NAME when creating a flow or standalone component. Tamara.NAME is a pre-built PaymentMethodName("tamara") constant exposed by the SDK:


1import com.checkout.components.paymentmethods.redirect.tamara.Tamara
2
3// Include Tamara in a Flow component (renders all available payment methods)
4val flow = checkoutComponents.create(ComponentName.Flow)
5
6// Or create a standalone Tamara component
7val tamaraComponent = checkoutComponents.create(Tamara.NAME)

Tamara only renders when the backend payment session includes it in supportedPaymentMethods. Creating the component when the session does not support it has no effect.

Render the component in Compose UI with Render() or in a View container with provideView():


1// Compose
2tamaraComponent.Render()
3
4// View
5tamaraComponent.provideView(containerView)

If the session body does not satisfy Tamara's eligibility rules, the method is not returned in supportedPaymentMethods and does not render, even if you pass it in the Tamara.NAME constant when creating the component.

Pass the providers you want to support to the providers: parameter when you create a flow component:


1import CheckoutComponents
2import CheckoutPaymentMethods
3
4let configuration = try await CheckoutComponents.Configuration(
5  paymentSession: session,
6  publicKey: "pk_...",
7  environment: .sandbox,
8  callbacks: callbacks
9)
10let sdk = CheckoutComponents(configuration: configuration)
11
12let flow = try sdk.create(
13  .flow(
14    options: [
15      .card(),
16      .applePay(merchantIdentifier: "merchant.com.example")
17    ],
18    providers: [CheckoutPaymentMethods.Provider.tamara]
19  )
20)

Additionally, if you only want to render Tamara, you can create a standalone Tamara component:


1import CheckoutComponents
2import CheckoutPaymentMethods
3
4let configuration = try await CheckoutComponents.Configuration(
5  paymentSession: session,
6  publicKey: "pk_...",
7  environment: .sandbox,
8  callbacks: callbacks
9)
10let sdk = CheckoutComponents(configuration: configuration)
11
12let tamara = try sdk.create(CheckoutPaymentMethods.Provider.tamara)

If the session body does not satisfy Tamara's eligibility rules, the method is not returned in supportedPaymentMethods and does not render, even if you pass it in the providers: array when creating the component.

Depending on the payment outcome, Checkout.com redirects the customer to the success_url or failure_url you specified when you created the PaymentSession.

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 appears in the webhook payload's data.metadata.cko_payment_session_id field.

You can listen to the existing onSuccess callback or onError callback to handle the payment response for Tamara payments, alongside card and Google Pay outcomes:


1val configuration = CheckoutComponentConfiguration(
2    context = context,
3    paymentSession = PaymentSessionResponse(
4        id = paymentSessionID,
5        paymentSessionToken = paymentSessionToken,
6        paymentSessionSecret = paymentSessionSecret,
7    ),
8    publicKey = "pk_...",
9    environment = Environment.SANDBOX, // or Environment.PRODUCTION
10    componentCallback = object : ComponentCallback {
11        override fun onSuccess(component: Component, paymentID: String) {
12            // Payment completed — navigate to confirmation screen
13        }
14        override fun onError(component: Component, error: CheckoutError) {
15            // Payment declined, failed, or cancelled — show error UI
16        }
17    }
18)

You can listen to the existing onSuccess callback or onError callback to handle the payment response for Tamara payments, alongside card and Apple Pay outcomes:


1let callbacks = CheckoutComponents.Callbacks(
2  onSuccess: { component, paymentID in
3    // Payment completed — navigate to confirmation screen
4  },
5  onError: { error in
6    // Payment declined or failed — show error UI
7  }
8)

If the customer dismisses the redirect, Flow does not trigger any callback.

Customize Flow for mobile

Learn how to customize Flow for mobile.

Flow for mobile library reference

See the configuration options and error handling steps for Flow for mobile.

Tamara for mobile app

How it works

Before you start

Add the SDK dependency

Create a new payment session
Server side

Note

Information

Request example

Response example

Enable Tamara in Flow for mobile

Handle the payment response
Client side

Next steps

Customize Flow for mobile

Flow for mobile library reference

How it works

Before you start

Add the SDK dependency

Create a new payment session Server side

Note

Information

Request example

Response example

Enable Tamara in Flow for mobile

Handle the payment response Client side

Next steps

Customize Flow for mobile

Flow for mobile library reference

Create a new payment session
Server side

Handle the payment response
Client side