Initiate Hosted Checkout Session(Tamara)

This endpoint allows you to initiate a Hosted Checkout Session with Tamara Buy Now, Pay Later enabled. The customer will be redirected to a secure EdfaPay checkout page where Tamara appears as a payment option, subject to eligibility and merchant activation.

Tamara uses the same Hosted Checkout initiate API — no separate endpoint is required.

Endpoint

POST https://api.edfapay.com/payment/initiate

Content-Type: multipart/form-data

Authentication

All requests to this endpoint require a valid edfa_merchant_id and a secure hash for request validation. The hash must be generated server-side using the provided algorithm, detailed in the Hash Generation section.

Prerequisites

Before using Tamara:

• Tamara must be activated on your merchant account by EdfaPay.
• Your integration must include itemized product details.

If Tamara is not enabled, it will not appear on the checkout page.

Request Parameters

product_details Field Overview

The product_details field allows you to include itemized details of the products or services in an order.
It is a JSON array of one or more product objects — each representing a single item in the purchase.

This field helps to:

• Provide a clear breakdown of the total order amount.
• Enhance clarity in payment records and invoices.
• Improve reporting, refunds, and reconciliation processes.

Structure of Each Product Object

Example of Product Details Field

"product_details": [
  {
    "reference_id": 150319445744795,
    "type": "invoice_product",
    "name": "HP Printer High Advanced",
    "sku": "HP-PRT-01",
    "quantity": 1,
    "amount": "100.00",
    "currency": "SAR"
  }
]

"product_details": [
  {
    "reference_id": 150319445744795,
    "type": "invoice_product",
    "name": "HP Printer",
    "sku": "HP-PRT-01",
    "quantity": 1,
    "amount": "100.00",
    "currency": "SAR"
  },
  {
    "reference_id": 150319445744796,
    "type": "invoice_product",
    "name": "Printer Ink Cartridge",
    "sku": "INK-01",
    "quantity": 2,
    "amount": "25.00",
    "currency": "SAR"
  }
]

Example cURL Request

curl --location 'https://apidev.edfapay.com/payment/initiate' \
--header 'Accept: application/json' \
--form 'edfa_merchant_id="TEST_MERCHANT_ID"' \
--form 'edfa_status="active"' \
--form 'payer_country="SA"' \
--form 'payer_address="Test Address"' \
--form 'order_amount="1250.00"' \
--form 'action="SALE"' \
--form 'sendBy="email"' \
--form 'payer_zip="12345"' \
--form 'order_id="TEST_ORDER_001"' \
--form 'payer_ip="127.0.0.1"' \
--form 'order_currency="SAR"' \
--form 'payer_first_name="Test"' \
--form 'payer_city="Riyadh"' \
--form 'auth="N"' \
--form 'payer_last_name="User"' \
--form 'payer_phone="+966500000000"' \
--form 'order_description="Test Invoice"' \
--form 'payer_email="[email protected]"' \
--form 'term_url_3ds="https://sandbox.edfapay.com/test/3ds"' \
--form 'client_key="TEST_CLIENT_KEY"' \
--form 'recurring_init="N"' \
--form 'req_token="N"' \
--form 'hash="TEST_HASH_VALUE"' \
--form 'product_details="[
  {\"reference_id\":\"TEST_REF_001\",\"type\":\"invoice_product\",\"name\":\"Test Item\",\"sku\":\"SKU001\",\"quantity\":1,\"amount\":\"1250.00\",\"currency\":\"SAR\"}
]"' \
--form 'locale="en"' \
--form 'shipping_first_name="Test"' \
--form 'shipping_last_name="User"' \
--form 'shipping_address="Test Shipping Address"' \
--form 'shipping_city="Riyadh"' \
--form 'shipping_country_code="SA"' \
--form 'tax_amount="0.00"' \
--form 'tax_currency="SAR"' \
--form 'shipping_amount="0.00"' \
--form 'shipping_currency="SAR"' \
--form 'merchant_success_url="https://sandbox.edfapay.com/test/success"' \
--form 'merchant_failure_url="https://sandbox.edfapay.com/test/failure"' \
--form 'merchant_cancel_url="https://sandbox.edfapay.com/test/cancel"' \
--form 'merchant_notification_url="https://sandbox.edfapay.com/test/notification"' \
--form 'expires_in_minutes="240"'

❗️

Important Note — Hash Generation

The hash parameter included in the request body is dynamically generated for each request and must not be hardcoded.

The hash value is calculated using specific request parameters combined with your merchant secret key. Any change in the request data requires regenerating the hash before sending the request.

🔗 For detailed steps and the exact formula used to generate the hash, refer to the Hash Generation Section.

Successful Response

{
  "redirect_url": "https://pay.edfapay.com/merchant/checkout/Test-Number/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

• redirect_url: Redirect your customer to this URL to complete the payment.

Hash Generation (Request Authentication)

To secure your API request, you must generate a hash using the request data and your secret merchant password. This hash ensures that the request is authentic and hasn’t been tampered with.

🚧

This hash is used solely to ensure the integrity of the request and is not related to the hash included in callback notifications.

Formula

hash = SHA1(MD5(UPPERCASE(order_id + order_amount + order_currency + order_description + merchant_password)))

Where Each Value Comes From:

• order_id: The same value used in your request body.
• order_amount: The same value used in your request body.
• order_currency: The same value used in your request body.
• order_description: The same value used in your request body.
• merchant_password: This is your secret merchant password (shared securely via email).

Notes on Hash Generation:

• The final result should be a lowercase hexadecimal string.
• The size of the hash must be equal to 40 characters.
• If any value differs between the hash and the request body (even a space or case change), the system will return an "Invalid Hash Value" error.

JavaScript Example

// Required: CryptoJS library

var order = {
  id: "Test-Number",
  amount: "0.11",
  currency: "SAR",
  description: "Test order"
};

var merchant = {
  pass: "YOUR_SECRET_MERCHANT_PASSWORD"
};

var to_md5 = (order.id + order.amount + order.currency + order.description + merchant.pass).toUpperCase();

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5).toString());
var result = CryptoJS.enc.Hex.stringify(hash);

console.log("Generated Hash:", result);

Callback Response

❗️

Important Notes

• Ensure product_details totals match order_amount.
• Tamara availability depends on merchant activation and customer eligibility.
• Refunds are processed only via the Merchant Dashboard.