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://app-api.edfapay.com/api/v1/payment-gateway/initiate

Content-Type: application/json

Authentication

All requests to this endpoint must include a valid X-API-KEY in the request header for authentication. The X-API-KEY must be sent from the server side and should not be exposed on the client side.

How to generate API key

Request Parameters

Field	Type	Required	Description
orderId	String	Yes	Unique identifier for the order.
currency	String	Yes	Currency code in ISO 4217 format (e.g., `SAR`).
amount	Decimal	Yes	Total amount to be charged.
customerDetails	Object	Yes	Customer information object.
address	Object	Optional	Customer address object.
recurringInit	String	Optional	Set to `Y` to initialize recurring payment.
successUrl	String	Yes	The endpoint to which the customer is redirected after a successful 3DS authentication.
failureUrl	String	Yes	The endpoint to which the customer is redirected after a failed 3DS authentication.
activityId	Integer	Optional	Sadad payment activity identifier.
issueDate	Date	Optional	Invoice issue date (YYYY-MM-DD).
expireDate	Date	Optional	Invoice expiration date (YYYY-MM-DD).

Customer Details Object

Field	Type	Required	Description
name	String	Yes	Full name of the customer.
email	String	Yes	Email address of the customer.
phone	String	Yes	Customer phone number.
idNumber	String	Optional	Customer identification number.
idType	String	Optional	Type of identification (e.g., Passport, National ID).
taxNumber	String	Optional	Customer tax number (if applicable).

Address Object

Field	Type	Description
country	String	Country code (e.g., `SA`).
state	String	State or governorate.
city	String	City name.
address	String	Full address details.
zip	String	Postal/ZIP code

Example cURL Request

curl --location 'https://app-api.edfapay.com/api/v1/payment-gateway/initiate' \
--header 'accept: */*' \
--header 'X-API-KEY: <Your API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "orderId": "12345",
  "currency": "SAR",
   "amount": 100,
  "customerDetails": {
    "name": "John Doe",
    "email": "John@edfapay.com",
    "phone": "+9665234678"	
  },
  "address": {
    "country": "SA",
    "state": "Riyadh",
    "city": "Riyadh",
    "address": "10 Olaya St, Floor 5, Apt 12"
  },
	"recurringInit": "N",
 	"successUrl": "https://www.success.com/",
  "failureUrl": "https://www.failure.com/"
}'

📘
If issueDate is not provided or is null, it will default to the current date. If expireDate is not provided or is null, it will automatically be set to 7 days after the issueDate.

Successful Response

{
    "code": 200,
    "message": "Success",
    "errorCode": null,
    "data": {
        "redirectUrl": "https://app.edfapay.com/pay/checkout?sessionId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}

👍
redirectUrl: Redirect your customer to this URL to complete the payment.

Important Notes

Do not expose your X-API-KEY to the client.

You will find the Initiate Request in the Postman Collection.

200OK

400Bad Request