Initiate Hosted Checkout Session

This document details how to initiate a hosted checkout session, redirecting your customer to a secure Edfapay payment page.

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.

Request Parameters

Field	Type	Required	Description
action	String	Yes	Transaction type. Use `"SALE"` for standard sale transactions.
edfa_merchant_id	String	Yes	Your unique merchant identifier issued by Edfapay.
order_id	String	Yes	Unique identifier for the transaction/order.
order_amount	Decimal	Yes	Amount to be charged (e.g., `0.11`).
order_currency	String	Yes	Currency code in ISO 4217 format (e.g., `SAR`,`AED`).
order_description	String	Yes	Description of the order.
req_token	String	Optional	`"Y"` to request a tokenized transaction; `"N"` otherwise.
payer_first_name	String	Yes	First name of the customer.
payer_last_name	String	Yes	Last name of the customer.
payer_address	String	Yes	Email or address of the customer.
payer_country	String	Yes	Country code (e.g., `SA`, `UAE`).
payer_city	String	Yes	City of the payer.
payer_zip	String	Yes	ZIP or postal code of the payer. Max length:5 digit
payer_email	String	Yes	Email address of the customer.
payer_phone	String	Yes	Customer’s phone number with country code.
payer_ip	String	Yes	IP-address of the Customer Must follow the format of IPv4 Example:XXX.XXX.XXX.XXX
checkout_expiry_mins	String	Optional	Payment link expiration time in minutes. Default value is 10080 (7 days).
term_url_3ds	String	Yes	URL that the customer is redirected to after completing 3D Secure authentication
auth	String	Optional	`"Y"` to authorize only, `"N"` for authorize+ capture (default).
recurring_init	String	Optional	`"Y"` if this transaction is a recurring initiation
hash	String	Yes	Secure hash for request authentication.

Example cURL Request

curl --location 'https://api.edfapay.com/payment/initiate' \\
--form 'action="SALE"' \\
--form 'edfa_merchant_id="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"' \\
--form 'order_id="Test-Number"' \\
--form 'order_amount="0.11"' \\
--form 'order_currency="SAR"' \\
--form 'order_description="Test order"' \\
--form 'req_token="N"' \\
--form 'payer_first_name="First"' \\
--form 'payer_last_name="Last"' \\
--form 'payer_address="Riyad"' \\
--form 'payer_country="SA"' \\
--form 'payer_city="Riyadh"' \\
--form 'payer_zip="12221"' \\
--form 'payer_email="example@gmail.com"' \\
--form 'payer_phone="966565555555"' \\
--form 'payer_ip="176.44.76.222"' \\
--form 'checkout_expiry_mins="10080"' \\
--form 'term_url_3ds="https://www.google.com/"' \\
--form 'auth="N"' \\
--form 'recurring_init="N"' \\
--form 'hash="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"'

curl --location 'https://api.edfapay.com/payment/initiate' \\
--form 'action="SALE"' \\
--form 'edfa_merchant_id="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"' \\
--form 'order_id="Test-Number"' \\
--form 'order_amount="0.11"' \\
--form 'order_currency="AED"' \\
--form 'order_description="Test order"' \\
--form 'req_token="N"' \\
--form 'payer_first_name="First"' \\
--form 'payer_last_name="Last"' \\
--form 'payer_address="Abu Dhabi "' \\
--form 'payer_country="UAE"' \\
--form 'payer_city="Dubai"' \\
--form 'payer_zip="00000"' \\
--form 'payer_email="example@gmail.com"' \\
--form 'payer_phone="971565555555"' \\
--form 'payer_ip="203.0.113.45"' \\
--form 'checkout_expiry_mins="10080"' \\
--form 'term_url_3ds="https://www.google.com/"' \\
--form 'auth="N"' \\
--form 'recurring_init="N"' \\
--form 'hash="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"'

📘
The payment link expiry is controlled using the checkout_expiry_mins parameter. This value represents the total validity period of the payment link in minutes.
Example:
Setting checkout_expiry_mins to 1440 will keep the payment link active for 1 day from the time it is generated.
If this parameter is not provided, the payment link will expire automatically after 10,080 minutes (7 days).

❗️
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 string.
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);

// Required: CryptoJS library

var order = {
  id: "Test-Number",
  amount: "0.11",
  currency: "AED",
  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);

Important Notes

Always generate the hash on the server-side.
Do not expose your merchant_password on the client.
If the hash is invalid, the API will return an error and not generate a checkout session.
term_url_3ds is not related to the webhook (callback) URL. It is only used to redirect the customer after 3D Secure authentication, while the webhook is for server-to-server transaction updates.
You will find the Initiate Request in the Postman Collection.

200Successful response

400Bad Request