# Tamara for Payment Setup API
To accept Tamara payments, you must:
1. Create a payment setup.
2. Enable initialization to check the customer's eligibility.
3. Confirm the payment.
4. Redirect the customer to Tamara.
---
## Create a payment setup
Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) 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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/payments/setups`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups`
### Request example
```json
{
"amount": 10000,
"currency": "SAR",
"reference": "ORD-5023-4E89",
"customer": {
"name": "Ali Farid",
"phone": {
"country_code": "966",
"number": "556002013"
}
},
"order": {
"shipping": {
"address": {
"address_line1": "123 King Fahd Rd",
"city": "Riyadh",
"zip": "11564",
"country": "SA"
}
}
},
"settings": {
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure"
}
}
```
In the request body, provide the following:
| Field | Description |
| --- | --- |
| `amount`
`number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).
Minimum: 1
**Required** |
| `currency`
`string` | Three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md).
Supported values:
- `SAR`
- `AED`
- `BHD`
- `KWD`
- `OMR`
**Required** |
| `customer.name`
`string` | The customer's full name.
Min length: 1
Max length: 225
Required to enable initialization. |
| `customer.email.address`
`string` | The customer's email address.
Format: email
Max length: 254
Required to enable initialization. |
| `customer.phone`
`object` | The customer's phone number.
Required to enable initialization. |
| `customer.phone.country_code`
`string` | The international dialing code for the customer's phone number.
Min length: 1
Max length: 7
Required to enable initialization. |
| `customer.phone.number`
`string` | The customer's phone number.
Max length: 25
Required to enable initialization. |
| `order`
`object` | The order details.
**Required** |
| `order.shipping`
`object` | The shipping details for the order.
Required to enable initialization. |
| `order.shipping.address`
`object` | The shipping address.
Required to enable initialization. |
| `order.shipping.address.address_line1`
`string` | The first line of the shipping address.
Min length: 1
Required to enable initialization. |
| `order.shipping.address.city`
`string` | The city of the shipping address.
Min length: 1
Required to enable initialization. |
| `order.shipping.address.country`
`string` | The two-letter ISO 3166 country code for the shipping address.
Required to enable initialization. |
| `order.shipping.address.zip`
`string` | The postal code of the shipping address.
Min length: 1
Required to enable initialization. |
| `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 |
| `payment_plan.type`
`string` | The customer's chosen Tamara payment plan.
Supported values:
- `pay_in_full`
- `pay_by_instalment_2`
- `pay_by_instalment_3`
- `pay_by_instalment_4`
- `pay_by_instalment_6`
- `pay_by_instalment_9`
- `pay_by_instalment_12`
- `pay_by_instalment_24`
- `pay_by_instalment_36`
- `pay_next_month` |
| `industry.accommodation`
`array[object]` | The accommodation-specific data, if applicable. |
| `industry.accommodation[].name`
`string` | Required when `industry.accommodation[]` is provided.
Min length: 1
**Conditional** |
| `industry.accommodation[].delivery_recipient`
`string` | Required when `industry.accommodation[]` is provided.
Min length: 1
**Conditional** |
| `industry.accommodation[].address.city`
`string` | Required when `industry.accommodation[]` is provided.
Min length: 1
**Conditional** |
| `industry.accommodation[].address.country`
`string` | Required when `industry.accommodation[]` is provided.
Min length: 1
**Conditional** |
| `industry.accommodation[].room`
`array[object]` | Required when `industry.accommodation[]` is provided.
Minimum items: 1
**Conditional** |
| `industry.accommodation[].room[].type`
`string` | Required when `industry.accommodation[].room` is provided.
Min length: 1
**Conditional** |
| `industry.airline[]`
`array[object]` | The airline-specific data, if applicable. |
| `industry.airline[].delivery_recipient`
`string` | Required when `industry.airline[]` is provided.
Min length: 1
**Conditional** |
| `industry.airline[].travel_type`
`string` | Required when `industry.airline[]` is provided.
Min length: 1
**Conditional** |
| `industry.airline[].trip_type`
`string` | Required when `industry.airline[]` is provided.
Min length: 1
**Conditional** |
| `industry.airline[].flight_leg_details`
`array[object]` | Required when `industry.airline[]` is provided.
Minimum items: 1
**Conditional** |
| `industry.airline[].flight_leg_details[].departure_airport`
`string` | Required when `industry.airline[].flight_leg_details` is provided.
Min length: 1
**Conditional** |
| `industry.airline[].flight_leg_details[].arrival_airport`
`string` | Required when `industry.airline[].flight_leg_details` is provided.
Min length: 1
**Conditional** |
| `industry.airline[].flight_leg_details[].carrier_code`
`string` | Required when `industry.airline[].flight_leg_details` is provided.
Min length: 1
**Conditional** |
| `industry.airline[].flight_leg_details[].class_of_travelling`
`string` | Required when `industry.airline[].flight_leg_details` is provided.
Min length: 1
**Conditional** |
| `industry.airline[].flight_leg_details[].departure_date`
`string` | The departure date of that flight leg.
Format: date |
| `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](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).
Minimum: 0
**Required** if `order.items` is provided. |
### Response example
```json
{
"id": "set_rcmepwrchqab2wsergcafvijfy",
"processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
"amount": 10000,
"currency": "SAR",
"payment_type": "Regular",
"reference": "ORD-5023-4E89",
"description": "Tamara payment",
"payment_methods": {
"tamara": {
"initialization": "disabled",
"status": "initialization_required",
"flags": []
}
},
"available_payment_methods": [
"tamara"
],
"settings": {
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure"
}
}
```
The response returns a `payment_methods` object, which contains the payment methods enabled on your account.
While `payment_methods.tamara.initialization` is `disabled`, the request is not validated against Tamara's rules and the `payment_methods.tamara` object shows an `initialization_required` [status](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api.md#Payment_method_status). To check the customer's eligibility, enable initialization.
---
## Enable initialization
When the customer selects Tamara, update the payment setup by calling the [Update a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint and provide:
- The payment setup `id` as the `{id}` path parameter.
- `payment_methods.tamara.initialization` set to `enabled`.
Enabling initialization triggers Tamara's eligibility assessment for the customer. The request must also carry the `reference`, `settings.success_url`, `settings.failure_url`, a `customer` (with `name`, `email.address`, and `phone`), and an `order.shipping.address`.
### Request example
**Production**
`PUT` `https://{prefix}.api.checkout.com/payments/setups/{id}`
**Sandbox**
`PUT` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}`
```json
{
"amount": 10000,
"currency": "SAR",
"reference": "ORD-5023-4E89",
"customer": {
"name": "Ali Farid",
"email": {
"address": "ali.farid@example.com"
},
"phone": {
"country_code": "966",
"number": "556002013"
}
},
"order": {
"shipping": {
"address": {
"address_line1": "123 King Fahd Rd",
"city": "Riyadh",
"zip": "11564",
"country": "SA"
}
}
},
"settings": {
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure"
},
"payment_methods": {
"tamara": {
"initialization": "enabled"
}
}
}
```
Optionally, provide a `payment_methods.tamara.risk_assessment` object with your own assessment of the customer:
| Field | Description |
| --- | --- |
| `payment_methods.tamara.risk_assessment.premium_customer`
`boolean` | Whether the customer is a premium customer. |
| `payment_methods.tamara.risk_assessment.risk_score`
`integer` | Your own risk score for the customer. |
| `payment_methods.tamara.risk_assessment.order_count_last24h`
`integer` | The number of orders the customer placed in the last 24 hours. |
| `payment_methods.tamara.risk_assessment.linked_device_count`
`integer` | The number of devices linked to the customer. |
### Response example
If the customer is eligible, the `payment_methods.tamara` object shows a `ready` status, and you can proceed to confirm the payment:
```json
{
"payment_methods": {
"tamara": {
"initialization": "enabled",
"status": "ready",
"flags": []
}
},
"available_payment_methods": [
"tamara"
]
}
```
If the customer is not eligible, the `payment_methods.tamara` object shows an `unavailable` status with the `ineligible_customer` flag, and Tamara is removed from `available_payment_methods`. Offer the customer another payment method.
```json
{
"payment_methods": {
"tamara": {
"initialization": "enabled",
"status": "unavailable",
"flags": [
"ineligible_customer"
]
}
},
"available_payment_methods": []
}
```
If Tamara returns its own risk assessment for the customer, it's echoed back on `payment_methods.tamara.risk_assessment`.
Two other outcomes are possible:
| Status | Description |
| --- | --- |
| `invalid` | The request failed Tamara's validation rules. The `flags` array names each field that failed validation. |
| `unavailable` with the `service_unavailable` flag | The eligibility check could not be completed. |
---
## Confirm the payment
Once the `payment_methods.tamara` status is `ready`, confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:
- The payment setup `id` as the `{id}` path parameter.
- `tamara` as the `{payment_method_name}` path parameter.
### Request example
**Production**
`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/tamara`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/tamara`
### Response example
```json
{
"id": "pay_er3uvjvfgpauje7o64agv3damy",
"status": "Pending",
"customer": {
"id": "cus_ujs5uvwcshhujllodxegkknwou"
},
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
},
"redirect": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy/redirect"
}
}
}
```
---
## Redirect the customer
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`.