Tamara for Payment Setup API

Last updated: April 30, 2026

To accept Tamara payments, you must:

Create a payment setup.
Confirm the payment.
Redirect the customer to Tamara.

Call the Create a payment setup endpoint.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "amount": 10000,
3  "currency": "SAR",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "name": "Ali Farid",
7    "phone": {
8      "country_code": "+966",
9      "number": "556002013"
10    }
11  },
12  "order": {
13    "shipping": {
14      "address": {
15        "address_line1": "123 King Fahd Rd",
16        "city": "Riyadh",
17        "zip": "11564",
18        "country": "SA"
19      }
20    }
21  },
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

In the request body, provide the following:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Supported values: `SAR`, `AED` Required
`customer.name` string	The customer's full name. Min length: 1 Max length: 225 Required
`customer.phone` object	The customer's phone number. Required
`customer.phone.country_code` string	The international dialing code for the customer's phone number. Min length: 1 Max length: 7 Required
`customer.phone.number` string	The customer's phone number. Max length: 25 Required
`order` object	The order details. Required
`order.shipping` object	The shipping details for the order. Required
`order.shipping.address` object	The shipping address. Required
`order.shipping.address.address_line1` string	The first line of the shipping address. Min length: 1 Required
`order.shipping.address.city` string	The city of the shipping address. Min length: 1 Required
`order.shipping.address.country` string	The two-letter ISO 3166 country code for the shipping address. Required
`order.shipping.address.zip` string	The postal code of the shipping address. Min length: 1 Required
`reference` string	A reference you can use to identify the payment. Max length: 80 Required
`settings.failure_url` string	The URL to redirect the customer to if the payment fails. Format: URI Max length: 1024 Required
`settings.success_url` string	The URL to redirect the customer to if the payment is successful. Format: URI Max length: 1024 Required
`billing` object	The customer's billing details.
`billing.address` object	The customer's billing address. Required if `billing` is provided.
`billing.address.address_line1` string	The first line of the billing address. Min length: 1 Max length: 200 Required if `billing` is provided.
`billing.address.address_line2` string	The second line of the billing address. Max length: 200
`billing.address.city` string	The city of the billing address. Min length: 1 Max length: 50 Required if `billing` is provided.
`billing.address.country` string	The two-letter ISO 3166 country code for the billing address. Min length: 2 Max length: 2 Required if `billing` is provided.
`billing.address.state` string	The state or region of the billing address. Max length: 3
`billing.address.zip` string	The postal code of the billing address. Max length: 50
`description` string	A description of the payment. Max length: 100
`order.items` array	An array of items in the order. Minimum items: 1
`order.items[].name` string	The name of the item. Min length: 1 Required if `order.items` is provided.
`order.items[].quantity` number	The quantity of the item. Minimum: 1 Required if `order.items` is provided.
`order.items[].unit_price` number	The unit price of the item, in the minor currency unit. Minimum: 0 Required if `order.items` is provided.


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 10000,
5  "currency": "SAR",
6  "payment_type": "Regular",
7  "reference": "ORD-5023-4E89",
8  "description": "Tamara payment",
9  "payment_methods": {
10    "tamara": {
11      "status": "ready",
12      "flags": []
13    }
14  },
15  "available_payment_methods": [
16    "tamara"
17  ],
18  "settings": {
19    "success_url": "https://example.com/payments/success",
20    "failure_url": "https://example.com/payments/failure"
21  }
22}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

When all required fields are present, the payment_methods.tamara object shows a ready status.

Confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
tamara as the {payment_method_name} path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/tamara


1{
2  "id": "pay_er3uvjvfgpauje7o64agv3damy",
3  "status": "Pending",
4  "customer": {
5    "id": "cus_ujs5uvwcshhujllodxegkknwou"
6  },
7  "_links": {
8    "self": {
9      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
10    },
11    "redirect": {
12      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy/redirect"
13    }
14  }
15}

Redirect the customer to the redirect.href URL from the response. The customer completes the payment on the Tamara page and is then redirected back to your settings.success_url or settings.failure_url.

Tamara for Payment Setup API

Create a payment setup

Information

Request example

Response example

Confirm the payment

Request example

Response example

Redirect the customer