Tamara
Beta

Last updated: August 16, 2023

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

Information

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

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

Tamara payments follow a two-step process:

Request a payment.
Redirect the customer to a Tamara's hosted payments page to complete the process.

Tamara offers two integration types — Buy Now Pay Later and Pay Now. However, you can also use the single checkout option, which means:

you can have only one Tamara button on your checkout page
the payment option selection is on Tamara’s hosted payments page

Using this integration type enables your customers to use Tamara’s Buy Now Pay Later products. The Buy Now Pay Later product is defined by the value passed in any product_type fields. If you want to have multiple payment options, you can add several buttons to the checkout page. The customer can then select the option they want before they’re redirected.

Using this integration type enables your customers to use Tamara’s Pay Now product. Like the Buy Now Pay Later products, the Pay Now product is also defined by the value passed in any product_type fields. If you want to have multiple payment options, you can add several buttons to the checkout page. For example, if you’re configured to use pay_in_full and pay_by_instalment_3, you would have two different buttons on your checkout page. The customer can then select the option they want before they’re redirected.

You can create multiple buttons on your checkout page for the customer to choose from, each of which is linked to a payment request with a defined product_type field. For example, let's say you want to include both the pay_now and pay_in_3 options. In this case, you would need to create two buttons, with two payment requests pointing to the different payment options.

To add these options to your checkout page, add whichever of the following values you need to the processing.product_type field of the payment request:

pay_in_full
pay_by_instalment_2
pay_by_instalment_3
pay_by_instalment_4
pay_by_instalment_6


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": "123 Anywhere St.",
30      "address_line2": "Apt. 456",
31      "city": "Anytown",
32      "state": "Riyadh Province",
33      "zip": "123456",
34      "country": "SA"
35    }
36  },
37  "capture": true,
38  "processing": {
39    "tax_amount": 0,
40    "shipping_amount": 0,
41    "product_type": "pay_by_instalment_3"
42  },
43  "items": [
44    {
45      "name": "item name",
46      "quantity": 2,
47      "unit_price": 2500,
48      "total_amount": 5000,
49      "tax_amount": 0,
50      "discount_amount": 0,
51      "reference": "description of item",
52      "image_url": "https://some_s3bucket.com",
53      "url": "https://some.website.com/item",
54      "sku": "123687000111"
55    },
56    {
57      "name": "Test",
58      "quantity": 2,
59      "unit_price": 2500,
60      "total_amount": 5000,
61      "tax_amount": 0,
62      "discount_amount": 0,
63      "reference": "description of item",
64      "image_url": "https://some_s3bucket.com",
65      "url": "https://some.website.com/item",
66      "sku": "123687000111"
67    }
68  ]
69}

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


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  "processing": {
15    "partner_payment_id": "2ef5d0b7-f491-4069-b436-1819b3809bda",
16    "product_type": "pay_by_instalment_3"
17  },
18  "_links": {
19    "self": {
20      "href": "https://api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
21    },
22    "redirect": {
23      "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"
24    }
25  }
26}

If you use this option, the customer will be redirected to Tamara's hosted payments page, with only one payment button available for them to select.

To enable this functionality, omit the processing.product_type field from 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}

For the full API specification, see the API reference.

post

https://api.checkout.com/payments

Redirect your customer to the redirect.href link in the response. This will enable the customer to authorize the payment before they are transferred to your predefined success or failure URL.

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

Buy Now Pay Later

Pay Now

Determining payment options

Request example

Response example

Single checkout

Request example

Response example

Information

Request a payment

Redirect the customer

Get details about a payment

Response example

Refund a payment

Request example

Response example

Cancel a payment

Webhooks

Testing Tamara