# Tamara for Unified Payments API

To accept Tamara payments, follow these steps:

1. [Request a payment](#Request_a_payment).
2. [Redirect the customer](#Redirect_the_customer).

---

## Request a payment

To send a payment request, call the [payments](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint.

**Live**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{ 
  "amount": 10000, 
  "currency": "SAR", 
  "source": {
    "type": "tamara",   
    "billing_address": {
    "address_line1": "123 Anywhere St.",
    "address_line2": "Apt. 456",
    "city": "Anytown",
    "state": "Riyadh Province",
    "zip": "123456",
    "country": "SA"
   }
 },
   "payment_type": "Installment",
   "payment_plan": {
     "total_number_of_payments": 2,
     "description": "Split into two payments or securely pay in full with Tamara"
 },
  "failure_url": "https://example.com",
  "success_url": "https://example.com",
  "reference": "ORD-5023-4E89",
  "processing_channel_id": "pc_whznpho6lkrunjg4h45bvcydfu",
  "customer": {
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "phone": {
      "country_code": "966",
      "number": "556002013"
   }
 },
  "shipping": {
    "address": {
      "address_line1": "123 Anywhere St.",
      "address_line2": "Apt. 456",
      "city": "Anytown",
      "state": "Riyadh Province",
      "zip": "123456",
      "country": "SA"
   }
 },
  "capture": true,
  "processing": {
    "tax_amount": 0,
    "shipping_amount": 0
 },
  "items": [
    {
      "name": "item name",
      "quantity": 2,
      "unit_price": 2500,
      "total_amount": 5000,
      "tax_amount": 0,
      "discount_amount": 0,
      "reference": "description of item",
      "image_url": "https://example.com/image",
      "url": "https://example.com/item",
      "sku": "123687000111"
    },
    {
      "name": "Test",
      "quantity": 2,
      "unit_price": 2500,
      "total_amount": 5000,
      "tax_amount": 0,
      "discount_amount": 0,
      "reference": "description of item",
      "image_url": "https://example.com/image",
      "url": "https://example.com/item",
      "sku": "123687000111"
    }
  ]
}
```

Tamara performs a credit assessment on each customer during the sign up and checkout process. In some cases, such as for marketplaces, travel, or high-risk industries, Tamara may require additional data to improve their risk assessment. This can include the following fields:

- `customer.summary.first_transaction_date`
- `customer.summary.last_payment_amount`
- `customer.summary.last_payment_date`
- `customer.summary.lifetime_value`
- `customer.summary.phone_verified`
- `customer.summary.premium_customer`
- `customer.summary.registration_customer`
- `customer.summary.returning_customer`
- `customer.summary.total_order_count`
- `source.stored`

### Response example

```json
 {
  "id": "pay_er3uvjvfgpauje7o64agv3damy",
  "requested_on": "2023-07-06T11:39:05.0933952Z",
  "source": {
    "type": "tamara"
  },
  "items": [
    {
      "name": "item name",
      "quantity": 2,
      "unit_price": 2500,
      "reference": "description of item",
      "image_url": "https://example.com/image",
      "url": "https://example.com/item",
      "total_amount": 5000,
      "tax_amount": 0,
      "discount_amount": 0,
      "sku": "123687000111"
    },
    {
      "name": "Test",
      "quantity": 2,
      "unit_price": 2500,
      "reference": "description of item",
      "image_url": "https://example.com/image",
      "url": "https://example.com/item",
      "total_amount": 5000,
      "tax_amount": 0,
      "discount_amount": 0,
      "sku": "123687000111"
    }
  ],
  "amount": 10000,
  "currency": "SAR",
  "payment_type": "Regular",
  "reference": "ORD-5023-4E89",
  "description": "Order Description",
  "status": "Expired",
  "approved": false,
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "jane.smith@example.com",
    "name": "Jane Smith",
    "phone": {
      "country_code": "966",
      "number": "556002013"
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 Anywhere St.",
      "address_line2": "Apt. 456",
      "city": "Anytown",
      "state": "Riyadh Province",
      "zip": "123456",
      "country": "SA"
    }
  },
  "processing": {
    "partner_payment_id": "2ef5d0b7-f491-4069-b436-1819b3809bda",
    "product_type": "pay_by_instalment_3",
    "locale": "en-US"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy/actions"
    }
  }
}
```

If you receive a `202 Accepted` response, with the `status` field set to `Pending`, your request was successful.

---

## Redirect the customer

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.

---

## Get details about a payment

Call the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails) endpoint and provide the payment ID as the `{id}` path parameter.

> **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**

`GET` `https://{prefix}.api.checkout.com/payments/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.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"`<br>`"payment_plan": { "total_number_of_payments": 2 }` | Split in 2 |
| `"payment_type": "Installment"`<br>`"payment_plan": { "total_number_of_payments": 3 }` | Split in 3 |
| `"payment_type": "Installment"`<br>`"payment_plan": { "total_number_of_payments": 4 }` | Split in 4 |
| `"payment_type": "Pay later"` | Pay Next Month |

### Response example

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.

```json
{
  "id": "pay_er3uvjvfgpauje7o64agv3damy",
  "requested_on": "2023-07-06T11:39:05.0933952Z",
  "source": {
    "type": "tamara"
  },
  "items": [
    {
      "name": "item name",
      "quantity": 2,
      "unit_price": 2500,
      "reference": "description of item",
      "image_url": "https://example.com/image",
      "url": "https://example.com/item",
      "total_amount": 5000,
      "tax_amount": 0,
      "discount_amount": 0,
      "sku": "123687000111"
    },
    {
      "name": "Test",
      "quantity": 2,
      "unit_price": 2500,
      "reference": "description of item",
      "image_url": "https://example.com/image",
      "url": "https://example.com/item",
      "total_amount": 5000,
      "tax_amount": 0,
      "discount_amount": 0,
      "sku": "123687000111"
    }
  ],
  "amount": 10000,
  "currency": "SAR",
  "payment_type": "Regular",
  "reference": "ORD-5023-4E89",
  "status": "Expired",
  "approved": false,
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "jane.smith@example.com",
    "name": "Jane Smith",
    "phone": {
      "country_code": "966",
      "number": "556002013"
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 Anywhere St.",
      "address_line2": "Apt. 456",
      "city": "Anytown",
      "state": "Riyadh Province",
      "zip": "123456",
      "country": "SA"
    }
  },
  "processing": {
    "partner_payment_id": "2ef5d0b7-f491-4069-b436-1819b3809bda",
    "product_type": "pay_by_instalment_3"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_er3uvjvfgpauje7o64agv3damy/actions"
    }
  }
}
```

---

## Refund a payment

Tamara supports both partial and full refunds. You can refund a payment through the [Dashboard](https://dashboard.checkout.com) or by using the [Refund API](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment).

For the full API specification, see the [API reference](https://api-reference.checkout.com).

> **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/{id}/refunds`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds`

### Request example

```json
{
 "amount": 100
}
```

### Response example

```json
{
  "action_id": "act_2zhdyofygycezfjfmqh4iiujoa",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_zt7jpwxhl2werecz2wvfourfya"
    }
  }
}
```

---

## Cancel a payment

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.

---

## Optional features

Optional features include:

* Risk assessment
* Travel industry data

### Risk assessment

Tamara performs a credit assessment on each customer as they go through the sign up and checkout process.

To ensure a better acceptance rate, provide as many fields as possible in the `customer` object when requesting the payment context:

- `customer.email`
- `customer.email_verified`
- `customer.name`
- `customer.phone`
- `customer.phone.country_code`
- `customer.phone.number`
- `customer.phone.phone_verified`

##### Request example

```json
{
  "source": {
    "type": "tamara"
  },
  "amount": 6540,
  "currency": "SAR",
  "capture": true,
  "reference": "ORD-5023-4E89",
  "description": "Set of 3 masks",
  "customer": {
    "email": "ali.farid@example.com",
    "email_verified": true,
    "name": "Ali Farid",
    "phone": {
      "country_code": "966",
      "number": "50 123 4567",
      "phone_verified": true
    },
    "summary": {
      "registration_date": "2021-08-24",
      "total_order_count": 10,
      "first_transaction_date": "2022-06-24",
      "last_payment_date": "2024-06-15",
      "last_payment_amount": 300
    },
    "shipping": {
      "address": {
        "address_line1": "PO Box 11111",
        "city": "Riyadh",
        "zip": "11564"
      }
    },
    "processing": {
      "shipping_amount": 300,
      "discount_amount": 100,
      "tax_amount": 3000,
      "locale": "ar"
    }
  },
  "items": [
    {
      "type": "Physical",
      "name": "Test item",
      "quantity": 2,
      "unit_price": 50,
      "reference": "858818ac",
      "discount_amount": 1000,
      "url": "string",
      "image_url": "string"
    }
  ],
  "processing_channel_id": "{{processing_channel_id}}",
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/fail"
}
```

### Travel industry data

If you're in the travel sector, provide the `processing.airline_data[]` object whenever possible in your payment request:

```json
{
  "processing": {
    "airline_data": [
      {
        "ticket": {
          "number": "045-21351455613"
        },
        "passenger": [
          {
            "first_name": "Ali",
            "last_name": "Farid",
            "date_of_birth": "1990-05-26"
          }
        ],
        "flight_leg_details": [
          {
            "travel_class": "Economy",
            "carrier_code": "BA",
            "departure_date": "2025-06-19",
            "departure_airport": "RUH",
            "arrival_airport": "LHR"
          },
          {
            "travel_class": "Economy",
            "carrier_code": "BA",
            "departure_date": "2025-06-23",
            "departure_airport": "RUH",
            "departure_time": "15:30",
            "arrival_airport": "LHR"
          }
        ]
      }
    ]
  }
}
```

---

## Testing Tamara

To start testing, contact your account manager or integrations engineer to activate Tamara payments in the sandbox environment.

1. Create a Tamara transaction and select the redirect link in the response to Tamara's website.
2. Sign in to the account by filling up one of the test phone numbers you have been provided with.
3. Confirm the one-time password (OTP) code — it should be pre-filled for you in the sandbox environment.
4. Fill in the card details, using one of the test card details provided to you.
5. Select _Submit_. You should then be redirected to your predefined success URL.