Tamara for Payment Setup API

Last updated: September 3, 2026

To accept Tamara payments, you must:

Create a payment setup.
Enable initialization to check the customer's eligibility.
Confirm the payment.
Redirect the customer to Tamara.

Call the Create a payment setup 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/payments/setups


1{
2  "amount": 10000,
3  "currency": "SAR",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "name": "Ali Farid",
7    "phone": {
8      "country_code": "966",
9      "number": "556002013"
10    }
11  },
12  "order": {
13    "shipping": {
14      "address": {
15        "address_line1": "123 King Fahd Rd",
16        "city": "Riyadh",
17        "zip": "11564",
18        "country": "SA"
19      }
20    }
21  },
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

In the request body, provide the following:

Field Description

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Supported values: `SAR` `AED` `BHD` `KWD` `OMR` Required
`customer.name` string	The customer's full name. Min length: 1 Max length: 225 Required to enable initialization.
`customer.email.address` string	The customer's email address. Format: email Max length: 254 Required to enable initialization.
`customer.phone` object	The customer's phone number. Required to enable initialization.
`customer.phone.country_code` string	The international dialing code for the customer's phone number. Min length: 1 Max length: 7 Required to enable initialization.
`customer.phone.number` string	The customer's phone number. Max length: 25 Required to enable initialization.
`order` object	The order details. Required
`order.shipping` object	The shipping details for the order. Required to enable initialization.
`order.shipping.address` object	The shipping address. Required to enable initialization.
`order.shipping.address.address_line1` string	The first line of the shipping address. Min length: 1 Required to enable initialization.
`order.shipping.address.city` string	The city of the shipping address. Min length: 1 Required to enable initialization.
`order.shipping.address.country` string	The two-letter ISO 3166 country code for the shipping address. Required to enable initialization.
`order.shipping.address.zip` string	The postal code of the shipping address. Min length: 1 Required to enable initialization.
`reference` string	A reference you can use to identify the payment. Max length: 80 Required
`settings.failure_url` string	The URL to redirect the customer to if the payment fails. Format: URI Max length: 1024 Required
`settings.success_url` string	The URL to redirect the customer to if the payment is successful. Format: URI Max length: 1024 Required
`billing` object	The customer's billing details.
`billing.address` object	The customer's billing address. Required if `billing` is provided.
`billing.address.address_line1` string	The first line of the billing address. Min length: 1 Max length: 200 Required if `billing` is provided.
`billing.address.address_line2` string	The second line of the billing address. Max length: 200
`billing.address.city` string	The city of the billing address. Min length: 1 Max length: 50 Required if `billing` is provided.
`billing.address.country` string	The two-letter ISO 3166 country code for the billing address. Min length: 2 Max length: 2 Required if `billing` is provided.
`billing.address.state` string	The state or region of the billing address. Max length: 3
`billing.address.zip` string	The postal code of the billing address. Max length: 50
`description` string	A description of the payment. Max length: 100
`payment_plan.type` string	The customer's chosen Tamara payment plan. Supported values: `pay_in_full` `pay_by_instalment_2` `pay_by_instalment_3` `pay_by_instalment_4` `pay_by_instalment_6` `pay_by_instalment_9` `pay_by_instalment_12` `pay_by_instalment_24` `pay_by_instalment_36` `pay_next_month`
`industry.accommodation` array[object]	The accommodation-specific data, if applicable.
`industry.accommodation[].name` string	Required when `industry.accommodation[]` is provided. Min length: 1 Conditional
`industry.accommodation[].delivery_recipient` string	Required when `industry.accommodation[]` is provided. Min length: 1 Conditional
`industry.accommodation[].address.city` string	Required when `industry.accommodation[]` is provided. Min length: 1 Conditional
`industry.accommodation[].address.country` string	Required when `industry.accommodation[]` is provided. Min length: 1 Conditional
`industry.accommodation[].room` array[object]	Required when `industry.accommodation[]` is provided. Minimum items: 1 Conditional
`industry.accommodation[].room[].type` string	Required when `industry.accommodation[].room` is provided. Min length: 1 Conditional
`industry.airline[]` array[object]	The airline-specific data, if applicable.
`industry.airline[].delivery_recipient` string	Required when `industry.airline[]` is provided. Min length: 1 Conditional
`industry.airline[].travel_type` string	Required when `industry.airline[]` is provided. Min length: 1 Conditional
`industry.airline[].trip_type` string	Required when `industry.airline[]` is provided. Min length: 1 Conditional
`industry.airline[].flight_leg_details` array[object]	Required when `industry.airline[]` is provided. Minimum items: 1 Conditional
`industry.airline[].flight_leg_details[].departure_airport` string	Required when `industry.airline[].flight_leg_details` is provided. Min length: 1 Conditional
`industry.airline[].flight_leg_details[].arrival_airport` string	Required when `industry.airline[].flight_leg_details` is provided. Min length: 1 Conditional
`industry.airline[].flight_leg_details[].carrier_code` string	Required when `industry.airline[].flight_leg_details` is provided. Min length: 1 Conditional
`industry.airline[].flight_leg_details[].class_of_travelling` string	Required when `industry.airline[].flight_leg_details` is provided. Min length: 1 Conditional
`industry.airline[].flight_leg_details[].departure_date` string	The departure date of that flight leg. Format: date
`order.items` array	An array of items in the order. Minimum items: 1
`order.items[].name` string	The name of the item. Min length: 1 Required if `order.items` is provided.
`order.items[].quantity` number	The quantity of the item. Minimum: 1 Required if `order.items` is provided.
`order.items[].unit_price` number	The unit price of the item, in the minor currency unit. Minimum: 0 Required if `order.items` is provided.

amount

number

The payment amount, in the minor currency unit.
Minimum: 1
Required

currency

string

Three-letter ISO 4217 currency code.
Supported values:

SAR
AED
BHD
KWD
OMR

Required

customer.name

string

The customer's full name.
Min length: 1
Max length: 225
Required to enable initialization.

customer.email.address

string

The customer's email address.
Format: email
Max length: 254
Required to enable initialization.

customer.phone

object

The customer's phone number.
Required to enable initialization.

customer.phone.country_code

string

The international dialing code for the customer's phone number.
Min length: 1
Max length: 7
Required to enable initialization.

customer.phone.number

string

The customer's phone number.
Max length: 25
Required to enable initialization.

order

object

The order details.
Required

order.shipping

object

The shipping details for the order.
Required to enable initialization.

order.shipping.address

object

The shipping address.
Required to enable initialization.

order.shipping.address.address_line1

string

The first line of the shipping address.
Min length: 1
Required to enable initialization.

order.shipping.address.city

string

The city of the shipping address.
Min length: 1
Required to enable initialization.

order.shipping.address.country

string

The two-letter ISO 3166 country code for the shipping address.
Required to enable initialization.

order.shipping.address.zip

string

The postal code of the shipping address.
Min length: 1
Required to enable initialization.

reference

string

A reference you can use to identify the payment.
Max length: 80
Required

settings.failure_url

string

The URL to redirect the customer to if the payment fails.
Format: URI
Max length: 1024
Required

settings.success_url

string

The URL to redirect the customer to if the payment is successful.
Format: URI
Max length: 1024
Required

billing

object

The customer's billing details.

billing.address

object

The customer's billing address.
Required if billing is provided.

billing.address.address_line1

string

The first line of the billing address.
Min length: 1
Max length: 200
Required if billing is provided.

billing.address.address_line2

string

The second line of the billing address.
Max length: 200

billing.address.city

string

The city of the billing address.
Min length: 1
Max length: 50
Required if billing is provided.

billing.address.country

string

The two-letter ISO 3166 country code for the billing address.
Min length: 2
Max length: 2
Required if billing is provided.

billing.address.state

string

The state or region of the billing address.
Max length: 3

billing.address.zip

string

The postal code of the billing address.
Max length: 50

description

string

A description of the payment.
Max length: 100

payment_plan.type

string

The customer's chosen Tamara payment plan.
Supported values:

pay_in_full
pay_by_instalment_2
pay_by_instalment_3
pay_by_instalment_4
pay_by_instalment_6
pay_by_instalment_9
pay_by_instalment_12
pay_by_instalment_24
pay_by_instalment_36
pay_next_month

industry.accommodation

array[object]

The accommodation-specific data, if applicable.

industry.accommodation[].name

string

Required when industry.accommodation[] is provided.
Min length: 1

Conditional

industry.accommodation[].delivery_recipient

string

Required when industry.accommodation[] is provided.
Min length: 1

Conditional

industry.accommodation[].address.city

string

Required when industry.accommodation[] is provided.
Min length: 1

Conditional

industry.accommodation[].address.country

string

Required when industry.accommodation[] is provided.
Min length: 1

Conditional

industry.accommodation[].room

array[object]

Required when industry.accommodation[] is provided.
Minimum items: 1

Conditional

industry.accommodation[].room[].type

string

Required when industry.accommodation[].room is provided.
Min length: 1

Conditional

industry.airline[]

array[object]

The airline-specific data, if applicable.

industry.airline[].delivery_recipient

string

Required when industry.airline[] is provided.
Min length: 1

Conditional

industry.airline[].travel_type

string

Required when industry.airline[] is provided.
Min length: 1

Conditional

industry.airline[].trip_type

string

Required when industry.airline[] is provided.
Min length: 1

Conditional

industry.airline[].flight_leg_details

array[object]

Required when industry.airline[] is provided.
Minimum items: 1

Conditional

industry.airline[].flight_leg_details[].departure_airport

string

Required when industry.airline[].flight_leg_details is provided.
Min length: 1

Conditional

industry.airline[].flight_leg_details[].arrival_airport

string

Required when industry.airline[].flight_leg_details is provided.
Min length: 1

Conditional

industry.airline[].flight_leg_details[].carrier_code

string

Required when industry.airline[].flight_leg_details is provided.
Min length: 1

Conditional

industry.airline[].flight_leg_details[].class_of_travelling

string

Required when industry.airline[].flight_leg_details is provided.
Min length: 1

Conditional

industry.airline[].flight_leg_details[].departure_date

string

The departure date of that flight leg.
Format: date

order.items

array

An array of items in the order.
Minimum items: 1

order.items[].name

string

The name of the item.
Min length: 1
Required if order.items is provided.

order.items[].quantity

number

The quantity of the item.
Minimum: 1
Required if order.items is provided.

order.items[].unit_price

number

The unit price of the item, in the minor currency unit.
Minimum: 0
Required if order.items is provided.


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 10000,
5  "currency": "SAR",
6  "payment_type": "Regular",
7  "reference": "ORD-5023-4E89",
8  "description": "Tamara payment",
9  "payment_methods": {
10    "tamara": {
11      "initialization": "disabled",
12      "status": "initialization_required",
13      "flags": []
14    }
15  },
16  "available_payment_methods": [
17    "tamara"
18  ],
19  "settings": {
20    "success_url": "https://example.com/payments/success",
21    "failure_url": "https://example.com/payments/failure"
22  }
23}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

While payment_methods.tamara.initialization is disabled, the request is not validated against Tamara's rules and the payment_methods.tamara object shows an initialization_required status. To check the customer's eligibility, enable initialization.

When the customer selects Tamara, update the payment setup by calling the Update a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
payment_methods.tamara.initialization set to enabled.

Enabling initialization triggers Tamara's eligibility assessment for the customer. The request must also carry the reference, settings.success_url, settings.failure_url, a customer (with name, email.address, and phone), and an order.shipping.address.

put

https://{prefix}.api.checkout.com/payments/setups/{id}


1{
2  "amount": 10000,
3  "currency": "SAR",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "name": "Ali Farid",
7    "email": {
8      "address": "ali.farid@example.com"
9    },
10    "phone": {
11      "country_code": "966",
12      "number": "556002013"
13    }
14  },
15  "order": {
16    "shipping": {
17      "address": {
18        "address_line1": "123 King Fahd Rd",
19        "city": "Riyadh",
20        "zip": "11564",
21        "country": "SA"
22      }
23    }
24  },
25  "settings": {
26    "success_url": "https://example.com/payments/success",
27    "failure_url": "https://example.com/payments/failure"
28  },
29  "payment_methods": {
30    "tamara": {
31      "initialization": "enabled"
32    }
33  }
34}

Optionally, provide a payment_methods.tamara.risk_assessment object with your own assessment of the customer:

Field	Description
`payment_methods.tamara.risk_assessment.premium_customer` boolean	Whether the customer is a premium customer.
`payment_methods.tamara.risk_assessment.risk_score` integer	Your own risk score for the customer.
`payment_methods.tamara.risk_assessment.order_count_last24h` integer	The number of orders the customer placed in the last 24 hours.
`payment_methods.tamara.risk_assessment.linked_device_count` integer	The number of devices linked to the customer.

If the customer is eligible, the payment_methods.tamara object shows a ready status, and you can proceed to confirm the payment:


1{
2  "payment_methods": {
3    "tamara": {
4      "initialization": "enabled",
5      "status": "ready",
6      "flags": []
7    }
8  },
9  "available_payment_methods": [
10    "tamara"
11  ]
12}

If the customer is not eligible, the payment_methods.tamara object shows an unavailable status with the ineligible_customer flag, and Tamara is removed from available_payment_methods. Offer the customer another payment method.


1{
2  "payment_methods": {
3    "tamara": {
4      "initialization": "enabled",
5      "status": "unavailable",
6      "flags": [
7        "ineligible_customer"
8      ]
9    }
10  },
11  "available_payment_methods": []
12}

If Tamara returns its own risk assessment for the customer, it's echoed back on payment_methods.tamara.risk_assessment.

Two other outcomes are possible:

Status	Description
`invalid`	The request failed Tamara's validation rules. The `flags` array names each field that failed validation.
`unavailable` with the `service_unavailable` flag	The eligibility check could not be completed.

Once the payment_methods.tamara status is ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
tamara as the {payment_method_name} path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/tamara


1{
2  "id": "pay_er3uvjvfgpauje7o64agv3damy",
3  "status": "Pending",
4  "customer": {
5    "id": "cus_ujs5uvwcshhujllodxegkknwou"
6  },
7  "_links": {
8    "self": {
9      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
10    },
11    "redirect": {
12      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy/redirect"
13    }
14  }
15}

Redirect the customer to the redirect.href URL from the response. The customer completes the payment on the Tamara page and is then redirected back to your settings.success_url or settings.failure_url.

Tamara for Payment Setup API

Create a payment setup

Information

Request example

Response example

Enable initialization

Request example

Response example

Confirm the payment

Request example

Response example

Redirect the customer