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://apidev.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

Example cURL Request

curl --location 'https://apidev.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="[email protected]"' \\
--form 'payer_phone="966565555555"' \\
--form 'payer_ip="176.44.76.222"' \\
--form 'term_url_3ds="https://www.google.com/"' \\
--form 'auth="N"' \\
--form 'recurring_init="N"' \\
--form 'hash="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"'

Successful Response

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

• redirect_url: Redirect your customer to this URL to complete the payment.
• Make sure that the domain in the redirect_url is sandbox.edfapay.com

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.

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);

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.