Initiate Hosted Checkout Session

This document details how to initiate a hosted checkout session, including split payment functionality, redirecting your customer to a secure Edfapay payment page while allowing payment distribution between multiple recipients.

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.
suppliers	Array	Optional	List of suppliers for split payment distribution.
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).

Suppliers Object

Field	Type	Required	Description
recipientId	String	Yes	Recipient identifier from Payout → Recipient Management.
amount	Decimal	Yes	Amount to be transferred to the specified recipient.

The recipientId can be obtained from Payout → Recipient Management in the merchant dashboard.

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,
  "suppliers": [
    {
      "recipientId": "659d66d3-e4f6-49c9-b393-ee5f94a99491",
      "amount": 2
    }
  ],
  "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.

200OK

400Bad Request