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 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 article, we walk you through how to use and manage the mentioned endpoint.


For the best practice , we highly recommed that you use the IPN or the call back to get the status of your transactions 



Through out the article we will use the transaction types clarified in our What is "tran_type"? solution article.   . 



In this article, you will be going to know about:

The Endpoint and Related Postman Collection


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 from here. The endpoint will need to be accessed with a POST request on the below-mentioned URL


Post{{domain}}/payment/query 


Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.

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:

    Parameter 

    Sample Response

    Nullable

    Purpose 

    tran_ref

    TST2234701408580

    ✔

    Indicates the Transaction Reference on the Paytabs side

    check details on [Response Parameters | tran_ref]

    profile_Id

    81784

    ✔

    Indicates the profile that created the transaction. 
      
    check details on [Request Parameters | profileId]



  • 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:

    Parameter 

    Sample Response

    Nullable

    Purpose 

    profile_Id

    81784

    ✔

    Indicates the profile that created the transaction. 
      
    check details on [Request Parameters | profileId]

    cart_id 

    STRING

    ✔

    Indicates the cart/order id at the merchant end to easily relate the transaction to

    To know more about this parameter please click here.


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.  

  • Query via Transaction Reference 

    {  "profile_id": "59020",  "tran_ref": "TST2016700000692"}
    Generic


  • Query via Cart ID

    {  "profile_id": "59020",  "cart_id": "cart_12212"}
    Generic

Sample Response Payloads


  • Query via Transaction Reference 

    {
  "tran_ref": "TST2105900091468",
  "tran_type": "Sale",
  "cart_id": "Sample Payment",
  "cart_description": "Sample Payment",
  "cart_currency": "EGP",
  "cart_amount": "1",
  "customer_details": {
    "name": "ALiaa Ahmed",
    "email": "[email protected]",
    "phone": "01005417901",
    "street1": "Alexandria",
    "city": "Alexandria",
    "state": "ALX",
    "country": "EG",
    "ip": "40.123.210.168"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G15046",
    "response_message": "Authorised",
    "transaction_time": "2021-02-28T12:24:06Z"
  },
  "payment_info": {
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111"
  }
}
    JavaScript


  • Query via Cart ID

    [
  {
    "tran_ref": "TST2220301299642",
    "tran_type": "Capture",
    "cart_id": "cart_id_1234",
    "cart_description": "Capture reason",
    "cart_currency": "AED",
    "cart_amount": "12.34",
    "customer_details": {
      "name": "wajih km",
      "email": "[email protected]",
      "phone": "0522222222"
    },
    "payment_result": {
      "response_status": "A",
      "response_code": "G72063",
      "response_message": "Authorised",
      "transaction_time": "2022-07-22T06:41:03Z"
    },
    "payment_info": {
      "card_type": "Credit",
      "card_scheme": "Visa",
      "payment_description": "4111 11## #### 1111"
    },
    "serviceId": 0
  },
  {
    "tran_ref": "TST2220301299641",
    "tran_type": "Auth",
    "cart_id": "cart_id_1234",
    "cart_description": "Description of the items/services",
    "cart_currency": "AED",
    "cart_amount": "12.34",
    "customer_details": {
      "name": "wajih km",
      "email": "[email protected]",
      "phone": "0522222222",
      "ip": "92.98.202.106"
    },
    "payment_result": {
      "response_status": "A",
      "response_code": "G72045",
      "response_message": "Authorised",
      "transaction_time": "2022-07-22T06:40:45Z"
    },
    "payment_info": {
      "card_type": "Credit",
      "card_scheme": "Visa",
      "payment_description": "4111 11## #### 1111"
    },
    "serviceId": 0
  }
]
    JavaScript








⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article. 

⇦ And to get familiar with the rest of the steps regarding the current step "Step 7 - Manage Transactions" kindly click here.

⇦ And to navigate to the previous step in the integration process "Step 6 - Handle the post payment responses" kindly click here.