Tamara for API only

Last updated: June 4, 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  "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  },
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}

Information

You must inspect the response to know your customer's chosen payment option after they complete the payment.

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  "payment_type": "Installment",
15  "payment_plan": {
16    "total_number_of_payments": 2,
17    "description": "Split in up to 2 payments or Pay in full securely with Tamara"      
18  },
19  "_links": {
20    "self": {
21      "href": "https://api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
22    },
23    "redirect": {
24      "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"
25    }
26  }
27}

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

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.

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.

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

Information

Response example

Redirect the customer

Get details about a payment

Response example

Refund a payment

Request example

Response example

Cancel a payment

Testing Tamara