Skip to main content

Query Transaction

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

you should know
For the best practice, we highly recommend that you use the IPN or the call back to get the status of your transactions for more details please checkHow to configure Instant Payment notification (IPN)?solution article.

you should know

Through out the article we will use the transaction types clarified in ourWhat is the "tran_type" (transaction type)?solution article.



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

POST{{domain}}/payment/query
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/query


The Minimum Required 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:

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 TypeRequired
profile_id
INT✔
Indicates the profile that created the transaction. check details on [Request Parameters | profileId].
{
    "profile_id": "987654"
}
tran_ref
STRING✔
Indicates the Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref]
{
    "tran_ref": "TST2234701408XXX"
}

Query via Cart ID​

As for this type, you can initiate query transaction requests using your profile_id and a cart_id, and you will receive an array of all the transactions that match this specific cart_id. Kindly check the request parameters' specifications below:

ParameterData TypeRequired
profile_id
INT✔
Indicates the profile that created the transaction. check details on [Request Parameters | profileId].
{
    "profile_id": "987654"
}
cart_id
STRING✔
Indicates the cart/order id at the merchant end to easily relate the transaction to. check details on[Response Parameters | cart_id]
{
    "cart_id": "CART#10001"
}
caution
Please check the following possible HTTPs error responses:

You only need to use one of the options listed above; if you provide both parameters cart_id or tran_ref in the Query request, you will receive an error. 400 Bad Request. 

{
    "code": 2,
    "message": "Invalid query. Only one of tranRef or cartId can be set.",
    "trace": "PMNT0401.66E1581A.00004763"
}


Sample Request Payloads​

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.

{
    "profile_id": "126***",
    "tran_ref": "TST201670000XXXX"
}


Sample Response Payloads​

{
    "tran_ref": "TST201670000XXXX",
    "tran_type": "Sale",
    "cart_id": "CART#10001",
    "cart_description": "Product/Service description",
    "cart_currency": "SAR",
    "cart_amount": "100",
    "customer_details": {
        "name": "Technical Support",
        "email": "[email protected]",
        "phone": "+966 55 xxxxxx6",
        "street1": "address street",
        "city": "Jeddah",
        "state": "Makkah",
        "country": "SA",
        "ip": "86.111.XXX.X"
    },
    "payment_result": {
        "response_status": "A",
        "response_code": "036501",
        "response_message": "Authorised",
        "acquirer_message": "00:Approved",
        "acquirer_rrn": "425509036501",
        "transaction_time": "2024-09-11T09:01:51Z"
    },
    "payment_info": {
        "payment_method": "MasterCard",
        "card_type": "Credit",
        "card_scheme": "MasterCard",
        "payment_description": "5500 00## #### 5559",
        "expiryMonth": 12,
        "expiryYear": 2026
    },
     "user_defined": {
         "udf1": "UDF1 Test",
         "udf2": "UDF2 Test",
         "udf3": "UDF3 Test",
         "udf4": "UDF4 Test",
         "udf5": "UDF5 Test",
         "udf6": "UDF6 Test",
         "udf7": "UDF7 Test",
         "udf8": "UDF8 Test",
         "udf9": "UDF9 Test"
     },
     "serviceId": 2,
     "token": "2C4654BC67A3EE30C6***0FF638B74B9",
     "profileId": 126***,
     "merchantId": 68***,
     "trace": "PMNT****.6760***.0006****"
}

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.