Tamara

Copy page

Copy page as Markdown for LLMs

Open in Claude

Ask questions about this page

Tamara is a Buy Now, Pay Later (BNPL) payment solution that allows customers to split their purchases into interest-free installments. Amazon Payment Services supports Tamara integration for seamless payment processing across multiple markets in the Middle East.

We support Tamara in KSA and UAE. Ensure your merchant account is configured for the appropriate market before integration.

API Endpoints

https://sbcheckout.payfort.com/FortAPI/paymentPage

https://checkout.payfort.com/FortAPI/paymentPage

Request Format

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Submission: HTML Form (Client-side HTTPS POST)

Request Parameters

Parameter
command   Alpha Max: 20 Required Transaction type to be executed. For Tamara payments, only PURCHASE is supported. Values: PURCHASE Example. PURCHASE
access_code   Alphanumeric Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Special characters: _ - . Example. XYZ9239-yu898
signature   Alphanumeric Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
phone_number   Numeric Max: 19 Required Customer phone number in international format. Required for Tamara eligibility verification. Special characters: + - ( ) **Space** Example. 00962797219966
amount   Numeric Max: 10 Required Payment amount in smallest currency unit (e.g., halalas for SAR, fils for AED). Must be positive integer. Example. 10000
currency   Alpha Max: 3 Required Three-letter ISO 4217 currency code. Tamara supports SAR and AED. Values: SAR, AED Example. AED
language   Alpha Max: 2 Required Checkout page and notification language. Supported values: en (English) or ar (Arabic). Example. en
customer_email   Alphanumeric Max: 254 Required Valid customer email address for payment notifications and receipt delivery. Special characters: _ - . @ + Example. customer@domain.com
payment_option   Alpha Max: 10 Required Payment method specification for Tamara transactions. Values: TAMARA Example. TAMARA
order_description   Alphanumeric Max: 150 Required Human-readable description of the order or service being paid for. Special characters: ' / . _ - # : $ **Space** Example. iPhone 6-S
customer_name   Alpha Max: 40 Optional Full name of the customer making the payment. Special characters: _ \ / - . ' **Space** Example. John Smith
customer_ip   Alphanumeric Max: 45 Optional Customer's IP address for fraud prevention. Mandatory if fraud service is activated. Supports both IPv4 and IPv6 formats. Special characters: . : Example. 192.178.1.10
convenience_fee   Numeric Max: 10 Optional Additional convenience fee in smallest currency unit. Consider currency decimal points when sending the fee. Example. 10000
settlement_reference   Alphanumeric Max: 22 Optional Unique reference passed to acquiring bank for settlement file identification. Example. XYZ9239-yu898
merchant_extra   Alphanumeric Max: 999 Optional Custom data that will be returned in the response and webhook notifications. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra5   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
return_url   Alphanumeric Max: 400 Optional Custom URL where customer will be redirected after payment completion. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com/return
order_metadata   Object Optional Airlines/Travel/Insurance Only: Structured metadata containing flight, insurance, and passenger details. Required only for travel and insurance transactions. Example. {'flight_reservation_details':{'pnr':'TR9088999'}}

Multiply your transaction amount by the currency decimal code per ISO code 3 before sending the amount parameter. Example: For 500 SAR (2 decimal places per ISO code 3), multiply by 100 to send 50000 in your request.

The merchant_reference must be unique per transaction.

Check signature calculation section to learn how to calculate the signature.

Airlines, Travel & Insurance Metadata

For airlines, travel, and insurance merchants, include the order_metadata parameter with the following structure:

Flight Details

Parameter
flight_reservation_details   Object Required Container object for all flight-related information. Example. {'pnr':'TR9088999','itinerary':[...]}
pnr   String Optional Passenger name record representing the trip booking number. Example. TR9088999
itinerary   Array Optional Array of flight segments containing departure and arrival details. Example. {'departure_city':'Dubai','arrival_city':'Riyadh'}
departure_city   String Optional City of departure for the flight segment. Example. Dubai
departure_country   String Optional Country of departure for the flight segment. Example. UAE
arrival_city   String Optional City of arrival for the flight segment. Example. Riyadh
arrival_country   String Optional Country of arrival for the flight segment. Example. KSA
carrier   String Optional Airline carrier name or code. Example. Emirates
departure_date   String Optional Departure date and time in ISO 8601 format. Example. 2018-10-17T07:26:33Z
class   String Optional Flight cabin class for the segment. Example. Economy
refundable   Boolean Optional Indicates if the ticket is eligible for refund. Example. true

Insurance Details

Parameter
insurance   Array Optional Array of insurance coverage details for the booking. Example. {'insurance_company':'Travel Guard','insurance_type':'personal'}
insurance_company   String Optional Name of the insurance provider company. Example. Travel Guard
insurance_type   String Optional Type of insurance coverage purchased. Example. personal
insurance_price   Integer Optional Insurance coverage amount in smallest currency unit. Example. 10000

Passenger Details

Parameter
passengers   Array Optional Array containing information for all passengers on the booking. Example. {'full_name':'John Doe','nationality':'American'}
full_name   String Optional Complete name of the passenger as it appears on travel documents. Example. John Doe
first_name   String Optional First name of the passenger. Example. John
last_name   String Optional Last name of the passenger. Example. Doe
dob   String Optional Date of birth of the passenger in YYYY-MM-DD format. Example. 1990-01-15
document_type   String Optional Type of identification document used by the passenger. Example. Passport
document_id   String Optional Identification number from the passenger's document. Example. A12345678
expiration_id_date   String Optional Expiration date of the passenger's identification document. Example. 2025-12-31
gender   String Optional Gender of the passenger. Values: M, F Example. M
affiliate_name   String Optional Name of the affiliate that originated the purchase. Example. Travel Agency XYZ

Flight Points

Parameter
flight_points_simple   Object Optional Simplified flight route information with IATA codes. Example. {'origin':{'air_code':'DXB'},'destination':{'air_code':'RUH'}}
origin   Object Optional Origin airport and city information. Example. {'air_code':'DXB','city_code':'DXB'}
air_code   String Optional IATA airport code for the origin. Example. DXB
city_code   String Optional IATA city code for the origin. Example. DXB
destination   Object Optional Destination airport and city information. Example. {'air_code':'RUH','city_code':'RUH'}
air_code   String Optional IATA airport code for the destination. Example. RUH
city_code   String Optional IATA city code for the destination. Example. RUH

Payment History

Parameter
payment_history_simple   Object Optional Customer payment history information for risk assessment. Example. {'paid_before_flag':true,'date_of_last_paid_purchase':'2023-08-15'}
unique_account_identifier   String Optional Unique identifier for the customer account across transactions. Example. CUST123456789
paid_before_flag   Boolean Optional Indicates whether the customer has previous successful payment records. Example. true
date_of_last_paid_purchase   String Optional Date of the customer's most recent successful payment in YYYY-MM-DD format. Example. 2023-08-15
date_of_first_paid_purchase   String Optional Date of the customer's first successful payment in YYYY-MM-DD format. Example. 2022-01-10

Response Parameters

Parameter
command   Alpha Max: 20 Transaction type executed. Values: PURCHASE Example. PURCHASE
access_code   Alphanumeric Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Unique order reference from the request. Special characters: _ - . Example. XYZ9239-yu898
amount   Numeric Max: 10 Transaction amount processed (includes convenience fee if applicable). Example. 10000
currency   Alpha Max: 3 Currency code used for the transaction. Example. AED
language   Alpha Max: 2 Language used for the checkout page. Example. en
customer_email   Alphanumeric Max: 254 Customer email address used. Special characters: _ - . @ + Example. customer@domain.com
signature   Alphanumeric Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
phone_number   Numeric Max: 19 Customer phone number from the request. Special characters: + - ( ) **Space** Example. 00962797219966
customer_name   Alpha Max: 40 Customer name from the request. Special characters: _ \ / - . ' **Space** Example. John Smith
fort_id   Numeric Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
payment_option   Alpha Max: 10 Payment method used for the transaction. Values: TAMARA Example. TAMARA
eci   Alpha Max: 16 E-commerce indicator for transaction type classification. Values: ECOMMERCE Example. ECOMMERCE
order_description   Alphanumeric Max: 150 Order description from the request. Special characters: ' / . _ - # : $ **Space** Example. iPhone 6-S
customer_ip   Alphanumeric Max: 45 Customer IP address from the request. Special characters: . : Example. 192.178.1.10
settlement_reference   Alphanumeric Max: 22 Settlement reference from the request. Example. XYZ9239-yu898
merchant_extra   Alphanumeric Max: 999 Custom data from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra5   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
return_url   Alphanumeric Max: 400 Return URL from the request. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com
response_message   Alphanumeric Max: 150 Human-readable response description in requested language. Example. Success
response_code   Numeric Max: 5 Numeric response code indicating transaction result. Example. 14000
status   Numeric Max: 2 Two-digit status code indicating transaction state. Example. 20

Every parameter sent by the merchant in the request will be returned in the response, including optional ones. The convenience_fee will not be returned separately; instead, the amount will include the sum of the order amount and convenience fee.

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Standard Request

<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="tamara_form">
    <!-- Required Transaction Parameters -->
    <input type="hidden" name="signature" value="2c862f1eb45796d990f7c9ccb796aef06b6a83861742cc494f8be45650f880a8">
    <input type="hidden" name="command" value="PURCHASE">
    <input type="hidden" name="merchant_reference" value="tesrtfgdged2358">
    <input type="hidden" name="amount" value="5000">
    <input type="hidden" name="access_code" value="AWhDMzqUiHeYJXFiMgaX">
    <input type="hidden" name="merchant_identifier" value="LbscwkFC">
    <input type="hidden" name="currency" value="SAR">
    <input type="hidden" name="language" value="en">
    
    <!-- Tamara Specific Parameters -->
    <input type="hidden" name="order_description" value="Premium Product">
    <input type="hidden" name="payment_option" value="TAMARA">
    <input type="hidden" name="phone_number" value="500000001">
    <input type="hidden" name="customer_email" value="otp.success@tamara.ai">
    
    <input type="submit" value="Pay with Tamara" id="submit_btn" name="submit_btn">
</form>

<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="tamara_travel_form">
    <!-- Standard Parameters (same as above) -->
    <input type="hidden" name="command" value="PURCHASE">
    <input type="hidden" name="access_code" value="lKZbvDhEc5s7EFhPmRFG">
    <input type="hidden" name="merchant_identifier" value="mVVJSDat">
    <input type="hidden" name="merchant_reference" value="22OctAirlineTest9093">
    <input type="hidden" name="payment_option" value="TAMARA">
    <input type="hidden" name="amount" value="100000">
    <input type="hidden" name="currency" value="SAR">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="customer_email" value="otp.success@tamara.ai">
    <input type="hidden" name="phone_number" value="500000001">
    <input type="hidden" name="order_description" value="Flight Booking - Dubai to Riyadh">
    <input type="hidden" name="signature" value="7bb0a4da01b142e92c7aa97df9c7be93dfd03a98631bc6b183da2f65ee754e91">
    
    <!-- Additional Airlines/Travel Parameter -->
    <input type="hidden" name="order_metadata" value="{'flight_reservation_details':{'pnr':'TR9088999','itinerary':[{'departure_city':'Dubai','departure_country':'UAE','arrival_city':'Riyadh','arrival_country':'KSA','carrier':'Emirates','departure_date':'2018-10-17T07:26:33Z','class':'Economy','refundable':true}],'insurance':[{'insurance_company':'Travel Guard','insurance_type':'personal','insurance_price':1800}],'passengers':[{'full_name':'John Doe','first_name':'John','last_name':'Doe','dob':'1990-01-15','document_type':'Passport','document_id':'A12345678','expiration_id_date':'2025-12-31','nationality':'American','gender':'M'}]},'flight_points_simple':{'origin':{'air_code':'DXB','city_code':'DXB'},'destination':{'air_code':'RUH','city_code':'RUH'}},'payment_history_simple':{'unique_account_identifier':'CUST123456789','paid_before_flag':true,'date_of_last_paid_purchase':'2023-08-15','date_of_first_paid_purchase':'2022-01-10'}}">
    
    <input type="submit" value="Book Flight with Tamara">
</form>

from flask import Flask, render_template_string

app = Flask(__name__)

@app.route('/tamara-checkout')
def tamara_checkout():
    form_html = '''
<!DOCTYPE html>
<html>
<head>
    <title>Tamara Payment Checkout</title>
</head>
<body>
    <h2>Pay with Tamara - Buy Now, Pay Later</h2>
    <p>Split your payment into interest-free installments</p>
    
    <form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="tamara_form">
        <input type="hidden" name="command" value="PURCHASE">
        <input type="hidden" name="access_code" value="AWhDMzqUiHeYJXFiMgaX">
        <input type="hidden" name="merchant_identifier" value="LbscwkFC">
        <input type="hidden" name="merchant_reference" value="tesrtfgdged2358">
        <input type="hidden" name="amount" value="5000">
        <input type="hidden" name="currency" value="SAR">
        <input type="hidden" name="language" value="en">
        <input type="hidden" name="order_description" value="Premium Product">
        <input type="hidden" name="payment_option" value="TAMARA">
        <input type="hidden" name="phone_number" value="500000001">
        <input type="hidden" name="customer_email" value="customer@example.com">
        <input type="hidden" name="signature" value="2c862f1eb45796d990f7c9ccb796aef06b6a83861742cc494f8be45650f880a8">
        <button type="submit">Pay with Tamara</button>
    </form>
</body>
</html>'''
    
    return form_html

if __name__ == '__main__':
    app.run(debug=True)

from flask import Flask, render_template_string
import json

app = Flask(__name__)

@app.route('/tamara-travel-checkout')
def tamara_travel_checkout():
    # Standard parameters + order_metadata for travel
    order_metadata = {
        "flight_reservation_details": {
            "pnr": "TR9088999",
            "itinerary": [{
                "departure_city": "Dubai",
                "departure_country": "UAE",
                "arrival_city": "Riyadh",
                "arrival_country": "KSA",
                "carrier": "Emirates",
                "departure_date": "2018-10-17T07:26:33Z",
                "class": "Economy",
                "refundable": True
            }],
            "passengers": [{
                "full_name": "John Doe",
                "first_name": "John",
                "last_name": "Doe",
                "dob": "1990-01-15",
                "document_type": "Passport",
                "document_id": "A12345678",
                "expiration_id_date": "2025-12-31",
                "nationality": "American",
                "gender": "M"
            }]
        },
        "flight_points_simple": {
            "origin": {"air_code": "DXB", "city_code": "DXB"},
            "destination": {"air_code": "RUH", "city_code": "RUH"}
        },
        "payment_history_simple": {
            "unique_account_identifier": "CUST123456789",
            "paid_before_flag": True,
            "date_of_last_paid_purchase": "2023-08-15",
            "date_of_first_paid_purchase": "2022-01-10"
        }
    }
    
    form_html = f'''
<!DOCTYPE html>
<html>
<head>
    <title>Tamara Travel Booking</title>
</head>
<body>
    <h2>Book Your Flight with Tamara</h2>
    <p>Pay for your travel in installments</p>
    
    <form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="tamara_travel_form">
        <!-- Standard Tamara Parameters -->
        <input type="hidden" name="command" value="PURCHASE">
        <input type="hidden" name="access_code" value="lKZbvDhEc5s7EFhPmRFG">
        <input type="hidden" name="merchant_identifier" value="mVVJSDat">
        <input type="hidden" name="merchant_reference" value="22OctAirlineTest9093">
        <input type="hidden" name="amount" value="100000">
        <input type="hidden" name="currency" value="SAR">
        <input type="hidden" name="language" value="en">
        <input type="hidden" name="order_description" value="Flight Booking - Dubai to Riyadh">
        <input type="hidden" name="payment_option" value="TAMARA">
        <input type="hidden" name="phone_number" value="500000001">
        <input type="hidden" name="customer_email" value="customer@example.com">
        <input type="hidden" name="signature" value="7bb0a4da01b142e92c7aa97df9c7be93dfd03a98631bc6b183da2f65ee754e91">
        
        <!-- Additional Travel Metadata -->
        <input type="hidden" name="order_metadata" value='{json.dumps(order_metadata)}'>
        
        <button type="submit">Book Flight with Tamara</button>
    </form>
</body>
</html>'''
    
    return form_html

if __name__ == '__main__':
    app.run(debug=True)

Sample Response

command=PURCHASE
access_code=AWhDMzqUiHeYJXFiMgaX
merchant_identifier=LbscwkFC
merchant_reference=tesrtfgdged2358
amount=5000
currency=SAR
language=en
response_code=14000
response_message=Success
status=20
fort_id=149295435400084008
payment_option=TAMARA
customer_email=otp.success@tamara.ai
phone_number=500000001
order_description=Premium Product
eci=ECOMMERCE
signature=7cad05f0212ed933c9a5d5dffa31661acf2c827a

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbcheckout.payfort.com/FortAPI/paymentPage
• Test Email: Use otp.success@tamara.ai for successful test transactions
• Test Phone: Use 500000001 for successful test scenarios

Go-Live Process

When ready to move to production, follow our Go-Live checklist.