Skip to main content

SADAD Query Transaction

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.

If you have a sadad transaction that you want to fetch its details and know more about its status, type, etc... you can use the sadad query transaction endpoint, as it will return the details of the requested transaction. In this article, we walk you through how to use and manage the mentioned endpoint.

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/inquiry
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.

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

Request Parameters​

To initiate a query payment request, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below according to the query type:

Sadad Query via Transaction Reference
In this type, you can initiate query transaction requests using your "profile_id" and the requested "tran_ref". You will receive a response object of this specific transaction you referred to. Kindly check the request parameters' specifications below:
ParameterData TypeMinMaxRequired
profile_id
INTAccept 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 PT Dashboard?tutorial article.
To know more about this parameter pleaseclick here.
{
    "profile_id": 987654
}
tran_ref
STRING
1
64
✔
Indicates the Transaction Reference on the PayTabs side.
For more information please check ourRequest/Response Parameters | Transaction Reference (tran_ref)..
{
     "tran_ref": "TST2234701408580"
}

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.

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.
{
    "profile_id": "59020",
    "tran_ref": "TST2016700000692"
        }

The Payment Flow Experience​

Reaching this stage, you are now able to track and understand theSADAD payment status through the expected flow behavior. Unlike the standard payment flow, SADAD follows a reference-based process where the final payment result depends on customer action. Below is an overview of how the SADAD status flow behaves:


  1. Initiating the SADAD Payment Request:
    1. The merchant’s system sends a SADAD payment request using the direct API.
    2. The request must comply with the structure and fields defined in theRequest & Response Payload Samples.

  2. Receiving the SADAD Reference:

    Once the request is successfully processed, the system returns a SADAD reference number, for example:"sadad_number":"23432001263"


  3. Default Payment Status Behavior:

    After the SADAD reference is generated, no immediate action is required from the merchant’s side. By default, if no payment action is taken by the customer, the payment status remains "pending". This is the expected and normal behavior until the customer completes or attempts the payment.


  4. Customer Completes the Payment:

    The merchant shares the SADAD reference number with the customer. The customer then accesses their bank platform, enters the SADAD number, and confirms the payment.

    If the customer successfully completes the payment, the SADAD status is updated to "paid".


  5. Declined or Failed Payments:

    In cases where the customer attempts payment but the transaction is declined, the payment status will reflect the failure. Detailed information explaining the reason for the decline is returned within thepayment_result object of the status response.


    This allows the merchant to review the failure reason and take appropriate next steps:

    {
    ........
    ........
    ........
    ,
        "payment_result": {
            "response_status": "D",
            "response_code": "300",
            "response_message": "Not authorised",
            "acquirer_message": "Invalid Request",
            "transaction_time": "2026-04-05T13:27:54Z"
        },
        "payment_info": {
            "payment_method": "SADAD (IFS)",
            "card_scheme": "Unknown",
            "payment_description": "Sadad (IFS)",
            "issuerCountry": "SA",
            "issuerName": "Sadad"
        },
        ........
        ........
    }


    to see the full response structure, please refer to the Request & Response Payload Samples section above.

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.