SADAD APIs | Create Payment Request

PayTabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.

Be Aware Of

Be aware that Sadad MUST be enabled in your PayTabs profile in order to perform any payments using it, so kindly make sure to contact [email protected] or your account manager requesting to enable Sadad.

Sadad is a payment method that is supported only in Saudi Arabia, and its payment workflow is a little bit different from payments via credit/debit card workflow. In the article, we will walk you through the transaction API via Sadad, for a better understanding of the request/response workflow.

---

The Endpoint and Related Postman Collection

In this tutorial, we will rely on the API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access fromKSA PayTabs Postman APIs Collection. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST	{{domain}}/payment/apm/sadad/ifs/request

Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

KSA

https://secure.paytabs.sa/payment/apm/sadad/ifs/request

---

Request Parameters

To initiate a direct payment request using this endpoint, there are minimum required parameters that need to be passed with valid information. The specification of both required parameters and all the other optional parameters/features that can be used are clarified below:

The Minimum Required Parameters

Parameter	Data Type	Min	Max	Required
profile_id	INT	Accept only valid profile number		✔
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check ourHow to get your account information from PT2 Dashboard?tutorial article. To know more about this parameter pleaseclick here.
	{ "profile_id": 987654 }
amount	INT	Accept only valid amount		✔
	The minimum amount is 25 SAR
	{ "amount": "100" }
customer.name	STRING	Accept only valid string		✔
	{ "customer.name": "unknown" }
customer.phone	STRING	Accept only valid phone number		✔
	{ "customer.phone": "05xxxxxxxx" }

The Available Optional Parameters

Parameter	Data Type	Min	Max	Required
customer.email	STRING	Valid Email Format		❌
	{ "customer": { "customer.email": "[email protected]" }
customer.street1	STRING	Accept Valid String		❌
	{ "customer": { "street1": "address street" }
customer.city	STRING	Accept Valid String		❌
	{ "customer": { "city": "Riyadh", } }
customer.state	STRING	Accept Valid String		❌
	{ "customer": { "state": "SA", } }
customer.zip	STRING	Accept Valid zip code		❌
	{ "customer": { "zip": "12345" } }

---

Request & Response Payload Samples

This section is dedicated give you a sample API request payload using the above mentioned required parameters, along with showing you the response payload received upon using the request payload.

Required Parameters Sample Payloads

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

Sample Request Payload

{                     
    "profile_id": 47125,
    "amount": 200,
    "customer": {
        "name": "John Smith",
        "phone": "0505555555",
    }
 }

Sample Response Payload

{
    "biller_id": "902",
    "sadad_number": "23432001263",
    "tran_ref": "TST2330900804629",
    "expire_date": "2023-11-10T08:02:38.901146134Z"
}

Optional Parameters Sample Payloads

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

Sample Request Payload

{
    "profile_id": 47125,
    "amount": 200,
    "customer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "0505555555",
        "street1": "404, 11th st, void",
        "city": "Riyadh",
        "state": "Riyadh",
        "zip": "12271"
    }

 }

Sample Response Payload

{
                                
    "biller_id": "902",
    "sadad_number": "23432001263",
    "tran_ref": "TST2330900804629",
    "expire_date": "2023-11-10T08:02:38.901146134Z"
}

---

The Payment Flow Experience

Reaching this point, you are now able to initiate an SADAD payment via the direct API request, the payment flow would vary than the normal payment flow you would be used to so here’s how it works:

1. Triggering the Sadad Payment Process:
   1. The merchant's system initiates a Sadad payment request.
   2. The Sadad Payment Request must follow the specifications outlined in the Request & Response Payload Samples.


2. Receiving Sadad Number: Upon a successful request, the Sadad system responds with the following key information:"sadad_number":"23432001263"


3. Sharing Sadad Number with the Customer: The merchant shares the Sadad Number with the customer. This can be done via on-screen display.


4. Customer Completes Payment: The customer opens the bank platform to enter the Sadad Number provided and confirms the payment.

As a Summary of Payment Flow:

1. The merchant’s system initiates a Sadad payment request.


2. Sadad responds with a Sadad Number.


3. The Sadad Number is shared with the customer.


4. The customer completes the payment using the Sadad Number in their bank platform.

Be Aware Of

Refunds for SADAD transactions are not supported via PayTabs. For any further help regarding refunds , please reach SADAD Team directly.