Tamara for API only

Last updated: July 16, 2025

To accept Tamara payments, follow these steps:

To send a payment request, call the payments endpoint.

post

https://api.checkout.com/payments


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  "description": "Order Description",
38  "status": "Expired",
39  "approved": false,
40  "customer": {
41    "id": "cus_ujs5uvwcshhujllodxegkknwou",
42    "email": "[email protected]",
43    "name": "Jane Smith",
44    "phone": {
45      "country_code": "+966",
46      "number": "556002013"
47    }
48  },
49  "shipping": {
50    "address": {
51      "address_line1": "123 Anywhere St.",
52      "address_line2": "Apt. 456",
53      "city": "Anytown",
54      "state": "Riyadh Province",
55      "zip": "123456",
56      "country": "SA"
57    }
58  },
59  "processing": {
60    "partner_payment_id": "2ef5d0b7-f491-4069-b436-1819b3809bda",
61    "product_type": "pay_by_instalment_3",
62    "locale": "en-US"
63  },
64  "_links": {
65    "self": {
66      "href": "https://api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
67    },
68    "actions": {
69      "href": "https://api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy/actions"
70    }
71  }
72}

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}

Tamara supports English and Arabic redirect landing pages. You can choose which language to display by setting the processing.locale field in your payment request to either:

en-US – for English
ar-AE – for Arabic

Redirect the 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.

Call the Get payment details endpoint and provide the payment ID as the {id} path parameter.

get

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

The payment_type and payment_plan fields contain the information of the payment option that your customer selected. The following table matches our payment_type and payment_plan values to their corresponding Tamara's payment types:

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

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.

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 for API only

Request a payment

Request example

Response example

Redirect the customer

Get details about a payment

Response example

Refund a payment

Request example

Response example

Cancel a payment

Testing Tamara