Tamara

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

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   String Max: 20 Required Transaction type to be executed. For Tamara payments, only PURCHASE is supported. Values: PURCHASE Example. PURCHASE
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   String Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
phone_number   String Max: 19 Required Customer phone number in international format. Required for Tamara eligibility verification. Example. 00962797219966
amount   Integer Max: 10 Required Payment amount in smallest currency unit (e.g., halalas for SAR, fils for AED). Must be positive integer. Example. 10000
currency   String Max: 3 Required Three-letter ISO 4217 currency code. Tamara supports SAR and AED. Values: SAR, AED Example. AED
language   String Max: 2 Required Checkout page and notification language. Supported values: en (English) or ar (Arabic). Example. en
customer_email   String Max: 254 Required Valid customer email address for payment notifications and receipt delivery. Example. customer@domain.com
payment_option   String Max: 10 Required Payment method specification for Tamara transactions. Values: TAMARA Example. TAMARA
order_description   String Max: 150 Required Human-readable description of the order or service being paid for. Example. iPhone 6-S
customer_name   String Max: 40 Optional Full name of the customer making the payment. Example. John Smith
customer_ip   String Max: 45 Optional Customer's IP address for fraud prevention. Mandatory if fraud service is activated. Supports both IPv4 and IPv6 formats. Example. 192.178.1.10
convenience_fee   Integer Max: 10 Optional Additional convenience fee in smallest currency unit. Consider currency decimal points when sending the fee. Example. 10000
settlement_reference   String Max: 22 Optional Unique reference passed to acquiring bank for settlement file identification. Example. XYZ9239-yu898
merchant_extra   String Max: 999 Optional Custom data that will be returned in the response and webhook notifications. Example. JohnSmith
merchant_extra1   String Max: 250 Optional Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra2   String Max: 250 Optional Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra3   String Max: 250 Optional Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra4   String Max: 250 Optional Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra5   String Max: 250 Optional Additional custom field for merchant-specific data. Example. JohnSmith
return_url   String Max: 400 Optional Custom URL where customer will be redirected after payment completion. 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   String Max: 20 Transaction type executed. Values: PURCHASE Example. PURCHASE
access_code   String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   String Max: 40 Unique order reference from the request. Example. XYZ9239-yu898
amount   Integer Max: 10 Transaction amount processed (includes convenience fee if applicable). Example. 10000
currency   String Max: 3 Currency code used for the transaction. Example. AED
language   String Max: 2 Language used for the checkout page. Example. en
customer_email   String Max: 254 Customer email address used. Example. customer@domain.com
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
phone_number   String Max: 19 Customer phone number from the request. Example. 00962797219966
customer_name   String Max: 40 Customer name from the request. Example. John Smith
fort_id   Integer Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
payment_option   String Max: 10 Payment method used for the transaction. Values: TAMARA Example. TAMARA
eci   String Max: 16 E-commerce indicator for transaction type classification. Values: ECOMMERCE Example. ECOMMERCE
order_description   String Max: 150 Order description from the request. Example. iPhone 6-S
customer_ip   String Max: 45 Customer IP address from the request. Example. 192.178.1.10
settlement_reference   String Max: 22 Settlement reference from the request. Example. XYZ9239-yu898
merchant_extra   String Max: 999 Custom data from the request. Example. JohnSmith
merchant_extra1   String Max: 250 Additional custom field from the request. Example. JohnSmith
merchant_extra2   String Max: 250 Additional custom field from the request. Example. JohnSmith
merchant_extra3   String Max: 250 Additional custom field from the request. Example. JohnSmith
merchant_extra4   String Max: 250 Additional custom field from the request. Example. JohnSmith
merchant_extra5   String Max: 250 Additional custom field from the request. Example. JohnSmith
return_url   String Max: 400 Return URL from the request. Example. https://www.merchant.com
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating transaction result. Example. 14000
status   String 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.