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`).
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 (ISO 3166-1 alpha-2), e.g., `"SA"`.
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
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="[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://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.

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.