| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
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.
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
recipientIdcan 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. |
| 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": "[email protected]",
"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
issueDateis not provided or is null, it will default to the current date. IfexpireDateis not provided or is null, it will automatically be set to 7 days after theissueDate.
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.