---
updatedAt: 2026-07-24T10:46:17.000Z
agentTools:
projectIndex: https://docs.tamara.co/llms.txt
---
# Create Checkout Session
This endpoint facilitates the creation of a checkout session, where all payment information is sent within the request to enable customer payments via Tamara. The response will include `order_id`, `checkout_id` , `status` and `checkout_url`.
Please store the `order_id` in your DBs to fetch the information about the order later and direct the customer to the `checkout_url` to seamlessly conclude the transaction through Tamara.
> ❗️ If you are integrating with us in the **UAE region**, please ensure to review the documentation here: [UAE ID Verification](https://docs.tamara.co/docs/uae-id-verification)
> 📘 For **critical lines of businesses**, please ensure to review the documentation here: Specific details for risk assessment
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "Tamara Public APIs v1.0",
"version": "1.0.0",
"contact": {}
},
"servers": [
{
"url": "https://{environment}.tamara.co/",
"variables": {
"environment": {
"enum": [
"api-sandbox",
"api"
],
"default": "api-sandbox",
"description": "Choose the environment you'd like to test on, either Sandbox (uses testing API tokens) `api-sandbox` or Production (uses live API tokens) `api`"
}
}
}
],
"components": {
"securitySchemes": {
"bearerToken": {
"type": "http",
"scheme": "bearer",
"description": "Enter the API token that is provided by Tamara to be sent in Authorization header."
}
}
},
"security": [
{
"bearerToken": []
}
],
"paths": {
"/checkout": {
"post": {
"tags": [
"Online Checkout"
],
"summary": "Create Checkout Session",
"description": "This endpoint facilitates the creation of a checkout session, where all payment information is sent within the request to enable customer payments via Tamara. The response will include `order_id`, `checkout_id` , `status` and `checkout_url`.
Please store the `order_id` in your DBs to fetch the information about the order later and direct the customer to the `checkout_url` to seamlessly conclude the transaction through Tamara.",
"operationId": "createCheckoutSession",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"order_reference_id",
"total_amount",
"description",
"country_code",
"payment_type",
"items",
"consumer",
"shipping_address",
"tax_amount",
"shipping_amount",
"merchant_url",
"instalments",
"risk_assessment"
],
"properties": {
"total_amount": {
"type": "object",
"description": "Total amount to be charged to consumer.",
"properties": {
"amount": {
"type": "number",
"example": 300,
"minimum": 0.1,
"default": 300
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"shipping_amount": {
"type": "object",
"description": "Total amount for the shipping of the order.",
"properties": {
"amount": {
"type": "string",
"example": 0,
"minimum": 0,
"default": 1
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"tax_amount": {
"type": "object",
"description": "Total amount of taxes, if additionally applied.\nNegative values should not be passed.",
"properties": {
"amount": {
"type": "string",
"example": 0,
"minimum": 0,
"default": 1
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"order_reference_id": {
"type": "string",
"description": "Unique order ID from the merchant's side, which will be used for settlement and reporting purposes. Can be modified after the checkout session is created.",
"example": "A1231234123",
"default": "abd12331-a123-1234-4567-fbde34ae"
},
"order_number": {
"type": "string",
"description": "The order number from the merchant side, this will be used for communication with the customer. If this value is not passed, the order_number will take the order_reference_id value.",
"example": "A1231234123",
"default": "A123125"
},
"discount": {
"type": "object",
"required": [
"name",
"amount"
],
"description": "This object is used to mention any customer-specific discount/voucher code being used for this specific order, but not to be used for site-wide discounts.",
"properties": {
"name": {
"type": "string",
"default": "Voucher A"
},
"amount": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"default": "300"
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED"
],
"default": "SAR"
}
},
"required": [
"amount",
"currency"
]
}
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"reference_id",
"type",
"name",
"sku",
"quantity",
"total_amount"
],
"description": "An array of objects to detail the items in this order as seperate objects for each item.",
"properties": {
"name": {
"type": "string",
"description": "Product name. `<=255 characters`.",
"example": "Lego City 8601",
"maximum": 255,
"default": "Lego City 8601"
},
"quantity": {
"type": "number",
"description": "The quantity being purchased for this specific item.",
"example": 1,
"default": 1
},
"reference_id": {
"type": "string",
"description": "The unique id of the item from merchant's side",
"example": "123",
"default": "123"
},
"type": {
"type": "string",
"example": "Digital, Physical...etc.",
"default": "Physical"
},
"sku": {
"type": "string",
"description": "Product SKU. **`<= 128 characters`**",
"example": "SA-12436",
"maximum": 128,
"default": "SA-12345"
},
"item_url": {
"type": "string",
"description": "URL of the item from merchant's website. **`<= 1024 characters`**",
"format": "uri",
"example": "SA-12436",
"maximum": 1024,
"default": "https://item-url.com/1234"
},
"image_url": {
"type": "string",
"description": "URL to an image of the product that can be later displayed to the customer. **`<= 1024 characters`**
**Size** = 2-3 MB maximum
**Resolution** WxH = 1024xY (the Y height of image should be small).",
"format": "uri",
"example": "SA-12436",
"maximum": 1024,
"default": "https://image-url.com/1234"
},
"unit_price": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 490,
"default": 100
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"tax_amount": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 10,
"minimum": 0,
"default": 1
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"discount_amount": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 100,
"minimum": 0
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
},
"total_amount": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"example": 100,
"default": 100
},
"currency": {
"type": "string",
"enum": [
"SAR",
"AED",
"BHD",
"KWD",
"OMR"
],
"example": "SAR",
"default": "SAR"
}
}
}
}
},
"default": [
{
"name": "Lego City 8601",
"type": "Digital",
"reference_id": "123",
"sku": "SA-12436",
"quantity": 1,
"discount_amount": {
"amount": 100,
"currency": "SAR"
},
"tax_amount": {
"amount": 10,
"currency": "SAR"
},
"unit_price": {
"amount": 490,
"currency": "SAR"
},
"total_amount": {
"amount": 100,
"currency": "SAR"
}
}
]
},
"consumer": {
"type": "object",
"description": "The customer's identifying details.",
"required": [
"first_name",
"last_name",
"phone_number"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"example": "customer@email.com",
"default": "customer@email.com"
},
"first_name": {
"type": "string",
"example": "Mona",
"default": "Mona"
},
"last_name": {
"type": "string",
"example": "Lisa",
"default": "Lisa"
},
"phone_number": {
"type": "string",
"example": "566027755",
"default": "566027755"
}
}
},
"country_code": {
"type": "string",
"description": "The two-character ISO 3166-1 country code",
"enum": [
"SA",
"AE",
"BH",
"KW",
"OM"
],
"example": "SA",
"default": "SA"
},
"description": {
"type": "string",
"description": "The order description.",
"example": "lorem ipsum dolor",
"maximum": 256,
"default": "Enter order description here."
},
"merchant_url": {
"type": "object",
"required": [
"success",
"failure",
"cancel"
],
"description": "This object includes all the redirect URLs that the customer will be redirected to from the Tamara checkout page in different cases.",
"properties": {
"cancel": {
"type": "string",
"format": "uri",
"example": "http://example.com/#/cancel",
"default": "http://example.com/#/cancel"
},
"failure": {
"type": "string",
"format": "uri",
"example": "http://example.com/#/fail",
"default": "http://example.com/#/fail"
},
"success": {
"type": "string",
"format": "uri",
"example": "http://example.com/#/success",
"default": "http://example.com/#/success"
}
}
},
"billing_address": {
"type": "object",
"description": "The customer's billing address, if any.",
"properties": {
"city": {
"type": "string",
"example": "Riyadh",
"default": "Riyadh"
},
"country_code": {
"type": "string",
"description": "The two-character ISO 3166-1 country code",
"enum": [
"SA",
"AE",
"BH",
"KW",
"OM"
],
"example": "SA",
"default": "SA"
},
"first_name": {
"type": "string",
"example": "Mona",
"default": "Mona"
},
"last_name": {
"type": "string",
"example": "Lisa",
"default": "Lisa"
},
"line1": {
"type": "string",
"example": "3764 Al Urubah Rd",
"default": "3764 Al Urubah Rd"
},
"line2": {
"type": "string",
"example": "string",
"default": "string"
},
"phone_number": {
"type": "string",
"example": "532298658",
"default": "532298658"
},
"region": {
"type": "string",
"example": "As Sulimaniyah",
"default": "As Sulimaniyah"
}
}
},
"shipping_address": {
"type": "object",
"required": [
"first_name",
"last_name",
"line1",
"city",
"country_code"
],
"properties": {
"city": {
"type": "string",
"example": "Riyadh",
"default": "Riyadh"
},
"country_code": {
"type": "string",
"description": "The two-character ISO 3166-1 country code",
"enum": [
"SA",
"AE",
"BH",
"KW",
"OM"
],
"example": "SA",
"default": "SA"
},
"first_name": {
"type": "string",
"example": "Mona",
"default": "Mona"
},
"last_name": {
"type": "string",
"example": "Lisa'",
"default": "Lisa"
},
"line1": {
"type": "string",
"example": "3764 Al Urubah Rd",
"default": "3764 Al Urubah Rd"
},
"line2": {
"type": "string",
"example": "string",
"default": "string"
},
"phone_number": {
"type": "string",
"example": "532298658",
"default": "532298658"
},
"region": {
"type": "string",
"example": "As Sulimaniyah",
"default": "As Sulimaniyah"
}
}
},
"platform": {
"type": "string",
"description": "Mentions the platform where the Tamara order is being initiated from (Mostly used by our e-commerce plugins) but can also be used by direct integrations.",
"example": "Magento, WooCommerce, Salla..etc.",
"default": "platform name here"
},
"is_mobile": {
"type": "boolean",
"description": "To identify mobile users of your store.",
"default": false,
"example": false
},
"locale": {
"type": "string",
"description": "Display language for Tamara checkout page. Language to be defined by the merchant following RFC 1766, e.g en_US or ar_SA. Default is set to Arabic if not passed and customer is new. If customer already exists and locale is not passed then customer's preference will be taken into account.",
"enum": [
"ar_SA",
"en_US"
],
"default": "ar_SA",
"example": "ar_SA"
},
"risk_assessment": {
"type": "object",
"description": "Risk assessment information from the merchant side",
"properties": {
"is_premium_customer": {
"type": "boolean",
"description": "Any subscription package/ VIP segmentation of customers(if available)",
"default": "false"
},
"account_creation_date": {
"type": "string",
"description": "Date when the customer registered their account at merchant (format: dd-mm-yyyy)",
"default": "01-01-2001"
},
"total_order_count": {
"type": "integer",
"description": "No. of successful orders of customer on merchant",
"default": "1"
},
"risk_score": {
"type": "integer",
"description": "Aggregated transaction/ customer risk score by merchant(if available)",
"default": "0"
},
"date_first_paid": {
"type": "string",
"description": "Date of first successful order. Will be null if first order (format: dd-mm-yyyy)",
"default": "01-01-2001"
},
"date_last_paid": {
"type": "string",
"description": "Date of last successful order. Will be null if first order (format: dd-mm-yyyy)",
"default": "01-01-2001"
},
"order_count_last_24h": {
"type": "integer",
"description": "No. of successful orders of customer on merchant, in the last 24 hours",
"default": "1"
},
"account_security": {
"type": "object",
"properties": {
"is_email_verified": {
"type": "boolean",
"default": "false",
"description": "true if email is verified by merchant."
},
"is_phone_verified": {
"type": "boolean",
"description": "true if phone is verified by merchant.",
"default": "false"
},
"password_last_changed": {
"type": "string",
"description": "Date of last password reset (format: dd-mm-yyyy).",
"default": "01-01-2001"
},
"last_login_date": {
"type": "string",
"description": "Date of last login (format: dd-mm-yyyy).",
"default": "01-01-2001"
},
"last_verification_method": {
"type": "string",
"description": "Method used for last authentication, for e.g., OTP, Biometric, etc..",
"default": "OTP"
},
"device_id": {
"type": "string",
"description": "Unique device fingerprint/ID from merchant. Any Hash (#) device ID",
"default": "#123"
},
"devices_linked": {
"type": "integer",
"description": "Number of active devices linked to the account.",
"default": "1"
}
},
"description": "Security and identity signals."
}
},
"required": [
"is_premium_customer",
"account_creation_date",
"total_order_count",
"date_first_paid",
"date_last_paid"
]
},
"expires_in_minutes": {
"type": "integer",
"description": "Order expiry time in minutes, min 5 minutes, max 1440 (one day). By default this key will be ignored, and default value of 30 mins is used, **Please contact our support team to enable this feature**.",
"example": 30,
"minimum": 5,
"maximum": 1440
},
"additional_data": {
"type": "object",
"description": "Any additional order data information from the merchant side",
"properties": {
"delivery_method": {
"type": "string",
"description": "the delivery method selected by the customer e.g. home delivery, or click and collect",
"example": "Home Delivery",
"default": "Home Delivery"
},
"pickup_store": {
"type": "string",
"description": "the collection point selected by the user if his order is for store collection",
"example": "Store A",
"default": "Store A"
},
"store_code": {
"type": "string",
"description": "The unique store code/name from which request is called",
"example": "Branch A",
"default": "Branch A"
},
"vendor_amount": {
"type": "number",
"description": "The amount to be settled to vendor",
"example": 10,
"default": 0
},
"merchant_settlement_amount": {
"type": "number",
"description": "The amount to be settled to merchant",
"example": 100,
"default": 0
},
"vendor_reference_code": {
"type": "string",
"description": "The vendor identifier",
"example": "AZ1234",
"default": "AZ1234"
}
}
}
}
},
"example": {
"total_amount": {
"amount": 300,
"currency": "SAR"
},
"shipping_amount": {
"amount": 0,
"currency": "SAR"
},
"tax_amount": {
"amount": 0,
"currency": "SAR"
},
"order_reference_id": "1231234123-abda-fdfe--afd31241",
"order_number": "S12356",
"discount": {
"name": "Christmas 2020",
"amount": {
"amount": 200,
"currency": "SAR"
}
},
"items": [
{
"name": "Lego City 8601",
"type": "Digital",
"reference_id": "123",
"sku": "SA-12436",
"quantity": 1,
"discount_amount": {
"amount": 100,
"currency": "SAR"
},
"tax_amount": {
"amount": 10,
"currency": "SAR"
},
"unit_price": {
"amount": 490,
"currency": "SAR"
},
"total_amount": {
"amount": 100,
"currency": "SAR"
}
}
],
"consumer": {
"email": "customer@email.com",
"first_name": "Mona",
"last_name": "Lisa",
"phone_number": "566027755"
},
"country_code": "SA",
"description": "lorem ipsum dolor",
"merchant_url": {
"cancel": "http://awesome-qa-tools.s3-website.me-south-1.amazonaws.com/#/cancel",
"failure": "http://awesome-qa-tools.s3-website.me-south-1.amazonaws.com/#/fail",
"success": "http://awesome-qa-tools.s3-website.me-south-1.amazonaws.com/#/success"
},
"billing_address": {
"city": "Riyadh",
"country_code": "SA",
"first_name": "Mona",
"last_name": "Lisa",
"line1": "3764 Al Urubah Rd",
"line2": "string",
"phone_number": "532298658",
"region": "As Sulimaniyah"
},
"shipping_address": {
"city": "Riyadh",
"country_code": "SA",
"first_name": "Mona",
"last_name": "Lisa",
"line1": "3764 Al Urubah Rd",
"line2": "string",
"phone_number": "532298658",
"region": "As Sulimaniyah"
},
"is_mobile": false,
"locale": "en_US",
"risk_assessment": {
"phone_verified": false,
"customer_age": 22,
"customer_dob": "31-01-2000",
"customer_gender": "Male",
"customer_nationality": "SA",
"is_premium_customer": true,
"is_existing_customer": true,
"is_guest_user": true,
"account_creation_date": "31-01-2019",
"platform_account_creation_date": "string",
"date_of_first_transaction": "31-01-2019",
"is_card_on_file": true,
"is_COD_customer": true,
"has_delivered_order": true,
"is_phone_verified": true,
"is_fraudulent_customer": true,
"total_ltv": 501.5,
"total_order_count": 12,
"order_amount_last3months": 301.5,
"order_count_last3months": 2,
"last_order_date": "31-01-2021",
"last_order_amount": 301.5,
"reward_program_enrolled": true,
"reward_program_points": 300
},
"additional_data": {
"delivery_method": "home delivery",
"pickup_store": "Store A",
"store_code": "Store code A",
"vendor_amount": 0,
"merchant_settlement_amount": 0,
"vendor_reference_code": "AZ1234"
}
}
}
}
},
"responses": {
"200": {
"description": "Checkout Session Created",
"content": {
"application/json": {
"schema": {
"properties": {
"checkout_id": {
"type": "string",
"format": "uuid"
},
"order_id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"checkout_url": {
"type": "string"
}
},
"x-readme-ref-name": "checkout"
},
"examples": {
"Success": {
"value": {
"order_id": "f56a3123-9e23-45e4-87a2-95366d3b0bca",
"checkout_id": "5ccbe4b1-890d-40b3-8a88-0b489ba8ed01",
"checkout_url": "https://checkout.tamara.co/checkout/5ccbe4b1-890d-40b3-8a88-0b489ba8ed01?locale=en_US&orderId=f56a3123-9e23-45e4-87a2-95366d3b0bca",
"status": "new"
}
}
}
}
}
},
"400": {
"description": "Unsupported Country/Currency",
"content": {
"application/json": {
"example": {
"message": "Unsupported country-currency combination. Please reach out to your account manager for support",
"errors": [
{
"error_code": "not_supported_country_currency"
}
],
"data": {},
"title": null,
"screen_type": null
}
}
}
}
}
}
}
},
"tags": [
{
"name": "Online Checkout"
}
],
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true,
"samples-languages": [
"json",
"shell",
"python",
"php",
"swift",
"http",
"java",
"kotlin",
"r",
"ruby",
"node",
"javascript",
"c",
"csharp",
"cplusplus",
"go",
"objectivec"
]
}
}
```