Tamara
Beta

Last updated: December 11, 2024

Tamara enables customers to perform secure online payments in the United Arab Emirates (UAE) and Saudi Arabia

Information

To enable Tamara payments on your account, contact your Account Manager or [email protected].

Tamara offers two payment types:

Split in X – Enables your customers to split the purchase amount over multiple payments over time.
Pay in full – Enables your customers to pay for the full purchase amount in a single payment.

The availability of these payment types varies depending on the:

Customer's country
Transaction currency
Transaction amount

Model	Collecting/Gateway
Payment flow	Redirect
Payment method types	Pay Now Buy Now Pay Later
Auto-capture payment
Capture
Refund
Partial refund
Return
Recurring payment

To accept Tamara payments, you must follow these steps:

When you send an initial payment context request, Tamara informs you of the available payment types you can offer. You then create multiple buttons on your checkout page for your customer to choose their preferred payment option.
Each button in your checkout page must trigger a subsequent payment request with the payment option selected by your customer.

Additionally, you can use the single checkout option to display a single Tamara button on your checkout page. This will redirect your customer to select their preferred payment type on Tamara's hosted payments page.

You must request a Checkout.com payment context to check the transaction's eligibility for Tamara's payment options.

To request a payment context, call the payment contexts endpoint:

Information

The Payment Contexts API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

post

https://api.checkout.com/payment-contexts


1{
2  "amount": 100,
3  "currency": "SAR",
4  "source": {
5    "type": "tamara"
6  },
7  "customer": {
8    "phone": {
9      "country_code": "+97",
10      "number": "544337766"
11    }
12  },
13  "processing": {
14    "locale": "en-US",
15    "purchase_country": "SA"
16  },
17  "processing_channel_id": "pc_kzxrrtssfbmefbv6vmf32hge2i"
18}

If you receive a 201 Created response code, your request was successful.

A successful request contains the following fields in the response's available_payment_types object:

payment_type – Tamara's supported payment types:
- Regular for Pay in full
- installment for Split in X
payment_plan – Details of the payment type, if payment_type is Installment


1{
2    "id": "pct_yydjaheyet4uhpsb35w7lwiaga",
3    "processed_on": "2024-09-24T14:13:11.6826526Z",
4    "partner_metadata": {
5        "single_checkout_enabled": true
6    },
7    "available_payment_types": [
8        {
9            "payment_type": "Installment",
10            "payment_plan": {
11                "total_number_of_payments": 4,
12                "description": "Split in up to 4 payments or Pay in full securely with Tamara"
13            }
14        }
15    ],
16    "_links": {
17        "self": {
18            "href": "https://gwc.ckotech.co/payment-contexts/pct_yydjaheyet4uhpsb35w7lwiaga"
19        }
20    }
21}

You must check the response for the available payment types and display one button per available payment type.

The following table matches Tamara's payment types to their corresponding payment_type and payment_plan fields:

Tamara payment plan	API fields
Pay in Full	`"payment_type": "Regular"`
Split in 2	`"payment_type": "Installments"` `"payment_plan": { "total_number_of_payments": 2 }`
Split in 3	`"payment_type": "Installments"` `"payment_plan": { "total_number_of_payments": 3 }`
Split in 4	`"payment_type": "Installments"` `"payment_plan": { "total_number_of_payments": 4 }`


1{
2  "available_payment_types": [
3    {
4      "payment_type": "Regular"
5    },
6    {
7      "payment_type": "Installment",
8      "payment_plan": {
9        "total_number_of_payments": 2,
10        "description": "Split in up to 2 payments or Pay in full securely with Tamara"
11      }
12    },
13    {
14      "payment_type": "Installment",
15      "payment_plan": {
16        "total_number_of_payments": 4,
17        "description": "Split in up to 4 payments or Pay in full securely with Tamara"
18      }
19    }
20  ]
21}

Each button in your checkout page must trigger a subsequent payment request using the corresponding payment_type and payment_plan fields with the payment option selected by your customer.

To send a payment request, call the payments endpoint.

post

https://api.checkout.com/payments


1{
2  "amount": 10000,
3  "currency": "SAR",
4  "source": {
5    "type": "tamara",
6    "billing_address": {
7      "address_line1": "123 Anywhere St.",
8      "address_line2": "Apt. 456",
9      "city": "Anytown",
10      "state": "Riyadh Province",
11      "zip": "123456",
12      "country": "SA"
13    }
14  },
15  "payment_type": "Installment",
16  "payment_plan": {
17    "total_number_of_payments": 2,
18    "description": "Split in up to 2 payments or Pay in full securely with Tamara"
19  },
20  "failure_url": "https://example.com",
21  "success_url": "https://example.com",
22  "reference": "ORD-5023-4E89",
23  "processing_channel_id": "pc_whznpho6lkrunjg4h45bvcydfu",
24  "customer": {
25    "name": "Jane Smith",
26    "email": "[email protected]",
27    "phone": {
28      "country_code": "+966",
29      "number": "556002013"
30    }
31  },
32  "shipping": {
33    "address": {
34      "address_line1": "123 Anywhere St.",
35      "address_line2": "Apt. 456",
36      "city": "Anytown",
37      "state": "Riyadh Province",
38      "zip": "123456",
39      "country": "SA"
40    }
41  },
42  "capture": true,
43  "processing": {
44    "tax_amount": 0,
45    "shipping_amount": 0
46  },
47  "items": [
48    {
49      "name": "item name",
50      "quantity": 2,
51      "unit_price": 2500,
52      "total_amount": 5000,
53      "tax_amount": 0,
54      "discount_amount": 0,
55      "reference": "description of item",
56      "image_url": "https://some_s3bucket.com",
57      "url": "https://some.website.com/item",
58      "sku": "123687000111"
59    },
60    {
61      "name": "Test",
62      "quantity": 2,
63      "unit_price": 2500,
64      "total_amount": 5000,
65      "tax_amount": 0,
66      "discount_amount": 0,
67      "reference": "description of item",
68      "image_url": "https://some_s3bucket.com",
69      "url": "https://some.website.com/item",
70      "sku": "123687000111"
71    }
72  ]
73}

If you receive a 202 Accepted response, with the status field set to Pending, your request was successful.


1{
2  "id": "pay_er3uvjvfgpauje7o64agv3damy",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_ujs5uvwcshhujllodxegkknwou",
7    "email": "[email protected]",
8    "name": "Jane Smith",
9    "phone": {
10      "number": "556002013",
11      "country_code": "+966"
12    }
13  },
14  "_links": {
15    "self": {
16      "href": "https://api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
17    },
18    "redirect": {
19      "href": "https://checkout-sandbox.tamara.co/checkout/a2328afc-9a3c-4483-a2aa-d9764ad92a1a?locale=en_US&orderId=2ef5d0b7-f491-4069-b436-1819b3809bda&show_item_images=with_item_images_shown&pay_the_difference_disclaimer=yellow&id_match_another_user=changing_phone&pay_in_full_value=value_support"
20    }
21  }
22}

Redirect your customer to the _links.redirect.href URL provided in the payment response. This redirection enables the customer to authenticate with Tamara and complete the payment.

This option redirects your customer to Tamara's hosted payments page, with one payment button available for them to select.

To enable this functionality, do not include the processing.payment_type field in the payment request.


1{
2  "amount": 10000,
3  "currency": "SAR",
4  "source": {
5    "type": "tamara",
6    "billing_address": {
7      "address_line1": "123 Anywhere St.",
8      "address_line2": "Apt. 456",
9      "city": "Anytown",
10      "state": "Riyadh Province",
11      "zip": "123456",
12      "country": "SA"
13    }
14  },
15  "failure_url": "https://example.com",
16  "success_url": "https://example.com",
17  "reference": "ORD-5023-4E89",
18  "processing_channel_id": "pc_whznpho6lkrunjg4h45bvcydfu",
19  "customer": {
20    "name": "Jane Smith",
21    "email": "[email protected]",
22    "phone": {
23      "country_code": "+966",
24      "number": "556002013"
25    }
26  },
27  "shipping": {
28    "address": {
29      "address_line1": "6901 At Takhassusi Branch Street",
30      "address_line2": "711-2880 Nulla St.",
31      "city": "Riyadh",
32      "state": "Riyadh Province",
33      "zip": "96522",
34      "country": "SA"
35    }
36  },
37  "capture": true,
38  "processing": {
39    "tax_amount": 0,
40    "shipping_amount": 0
41  },
42  "items": [
43    {
44      "name": "item name",
45      "quantity": 2,
46      "unit_price": 2500,
47      "total_amount": 5000,
48      "tax_amount": 0,
49      "discount_amount": 0,
50      "reference": "description of item",
51      "image_url": "https://some_s3bucket.com",
52      "url": "https://some.website.com/item",
53      "sku": "123687000111"
54    },
55    {
56      "name": "Test",
57      "quantity": 2,
58      "unit_price": 2500,
59      "total_amount": 5000,
60      "tax_amount": 0,
61      "discount_amount": 0,
62      "reference": "description of item",
63      "image_url": "https://some_s3bucket.com",
64      "url": "https://some.website.com/item",
65      "sku": "123687000111"
66    }
67  ]
68}

If you receive a 202 Accepted response, with a status field set to Pending, your request was successful. You now need to redirect your customer as described in the following example.

Information

You will be notified of the customer's chosen payment option when the customer completes the payment.


1{
2  "id": "pay_xtg3pcf5mwzuxpx3peucodzw7e",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_ujs5uvwcshhujllodxegkknwou",
7    "email": "[email protected]",
8    "name": "Jane Smith",
9    "phone": {
10      "number": "556002013",
11      "country_code": "+966"
12    }
13  },
14  "processing": {
15    "partner_payment_id": "0dce4004-29c5-421c-9b3e-918d9c237e5c"
16  },
17  "_links": {
18    "self": {
19      "href": "https://api.sandbox.checkout.com/payments/pay_xtg3pcf5mwzuxpx3peucodzw7e"
20    },
21    "redirect": {
22      "href": "https://checkout-sandbox.tamara.co/checkout/a3c3c0e9-bb73-4af0-ac00-83c60794f7f7?locale=en_US&orderId=0dce4004-29c5-421c-9b3e-918d9c237e5c&show_item_images=with_item_images_shown&pay_the_difference_disclaimer=blue1&pay_in_full_value=value_support"
23    }
24  }
25}

You can retrieve details about an existing Tamara payment with the following endpoints.

For the full API specification, see the API reference.

get

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

Depending on the merchant integration type and the payment status, information about the product_type may not be available. It may also not be part of the GET response.

If the payment has a captured status, the payment response will display the product_type field, showing the payment option selected by the customer.


1{
2  "id": "pay_er3uvjvfgpauje7o64agv3damy",
3  "requested_on": "2023-07-06T11:39:05.0933952Z",
4  "source": {
5    "type": "tamara"
6  },
7  "items": [
8    {
9      "name": "item name",
10      "quantity": 2,
11      "unit_price": 2500,
12      "reference": "description of item",
13      "image_url": "https://some_s3bucket.com",
14      "url": "https://some.website.com/item",
15      "total_amount": 5000,
16      "tax_amount": 0,
17      "discount_amount": 0,
18      "sku": "123687000111"
19    },
20    {
21      "name": "Test",
22      "quantity": 2,
23      "unit_price": 2500,
24      "reference": "description of item",
25      "image_url": "https://some_s3bucket.com",
26      "url": "https://some.website.com/item",
27      "total_amount": 5000,
28      "tax_amount": 0,
29      "discount_amount": 0,
30      "sku": "123687000111"
31    }
32  ],
33  "amount": 10000,
34  "currency": "SAR",
35  "payment_type": "Regular",
36  "reference": "ORD-5023-4E89",
37  "status": "Expired",
38  "approved": false,
39  "customer": {
40    "id": "cus_ujs5uvwcshhujllodxegkknwou",
41    "email": "[email protected]",
42    "name": "Jane Smith",
43    "phone": {
44      "country_code": "+966",
45      "number": "556002013"
46    }
47  },
48  "shipping": {
49    "address": {
50      "address_line1": "123 Anywhere St.",
51      "address_line2": "Apt. 456",
52      "city": "Anytown",
53      "state": "Riyadh Province",
54      "zip": "123456",
55      "country": "SA"
56    }
57  },
58  "processing": {
59    "partner_payment_id": "2ef5d0b7-f491-4069-b436-1819b3809bda",
60    "product_type": "pay_by_instalment_3"
61  },
62  "_links": {
63    "self": {
64      "href": "https://api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
65    },
66    "actions": {
67      "href": "https://api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy/actions"
68    }
69  }
70}

Tamara supports both partial and full refunds. You can refund a payment through the Dashboard or by using the Refund API.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments/{id}/refunds


1{
2 "amount": 100
3}


1{
2  "action_id": "act_2zhdyofygycezfjfmqh4iiujoa",
3  "_links": {
4    "payment": {
5      "href": "https://api.checkout.sandbox.com/payments/pay_zt7jpwxhl2werecz2wvfourfya"
6    }
7  }
8}

If the customer does not complete their payment, we will expire the payment and send a payment_expired webhook within 30 minutes. If the customer cancels their payment, we will send a payment_expired webhook.

Once a payment is created, it cannot be voided by the merchant. To void a payment in progress, wait for the payment_captured webhook, and then process a refund. Communicating this in advance to your end customer can help you avoid chargebacks.

When using Tamara, you may receive the following webhooks.

Webhook	Description
`payment_capture_pending`	Sent when a payment request has been accepted by the payment provider (Tamara)
`payment_captured`	Sent when the payment has been successfully captured
`payment_declined`	Sent when a payment request has been rejected
`payment_expired`	Sent when the payment has expired or was canceled by the customer (usually after 30 minutes)
`payment_pending`	Sent when a payment request has been successfully initiated and accepted by Checkout.com
`payment_refund_declined`	Sent when a refund has been declined
`payment_refund_pending`	Sent when the refund of the payment has been (fully or partially) accepted
`payment_refunded`	Sent when the payment has been (fully or partially) refunded

To start testing, contact your Account Manager or Integrations Engineer to activate Tamara payments in the sandbox environment.

Create a Tamara transaction and select the redirect link in the response to Tamara's website.
Sign in to the account by filling up one of the test phone numbers you have been provided with.
Confirm the one-time password (OTP) code — it should be pre-filled for you in the sandbox environment.
Fill in the card details, using one of the test card details provided to you.
Select Submit. You should then be redirected to your predefined success URL.

Tamara
Beta

Information

Tamara payment flow

Request a payment context

Information

Request example

Response example

Check available payment options

Request example

Request a payment

Request example

Response example

Redirect your customer

Single checkout

Request example

Response example

Information

Get details about a payment

Response example

Refund a payment

Request example

Response example

Cancel a payment

Webhooks

Testing Tamara