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. 



An invoice is a document you send to your client after purchasing goods or services from you, both as a means of recording the sale and requesting payment from them. You can catch everything you need about PayTabs invoices in our what PayTabs Invoices is? solutions article.


If you have an invoice that you want to fetch its status, you can use the query invoice status endpoint. In this article, we walk you through how to use and manage the mentioned endpoint. We highly recommend that you and your team check the "Step 3.1.4 - Invoices | Payment Workflow" solution article first to understand the business/logic this integration type relay on


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 invoices 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/invoice/{{invoice_id}}/status



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.



What is invoice status? 



Once you have created an invoice, it can be stated with a specific status, such as  :


  • Paid ( which means that the invoice is successfully paid)
  • Pending (which means that the invoice is not ready or waiting for more configurations)
  • Canceled ( which means that the invoice has been canceled)


This article is dedicated to walking you through the valid way to inquire about the status of a specific invoice using the invoice status request.


The Minimum Required Parameters


To initiate a query invoice 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:



  • via a GET Request

    In the GET invoice status, we simply use a GET request passing only the {{invoice_id}}} as a param in the endpoint URL to get the status. As shown in the below sample request.



  • via a POST Request

    In the POST invoice status, we simply use a POST request with only the "invoice_id" and "profile_id" as payload parameters to get the status. As shown below:

    Parameter

    Data Type

    Required

    Purpose

    profile_id 

    INT

    ✔

    The merchant Profile ID you can get from your PayTavs dashboard. For more information please check our How to get your account information from PT2 Dashboard? solution article.

    To know more about this parameter please click here.

    invoice_id

    INT

    ✔

    Indicates the invoice reference you want to query.

    To know more about this parameter please click here.


Sample Request Payload 


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 according to the query type:


  • via a GET Request 

    curl --location --request GET 'https://secure-egypt.paytabs.com/payment/invoice/2070442/status' \
--header 'Authorization: SBJNZBM2GJ-J26LHBRWLH-6TMNHNL9WM'

  • via a POST Request

    curl --location --request POST 'https://secure-egypt.paytabs.com/payment/invoice/status' \
--header 'Authorization: SBJNZBM2GJ-J26LHBRWLH-6TMNHNL9WM' \
--header 'Content-Type: application/json' \
--data-raw '{
    "profile_id": 79010,
    "invoice_id": {{invoice_id}}
}'


Sample Response Payload


When an invoice is paid, it results in creating a new transaction, and you will receive the transaction details in the status response. 

{
    "invoice_status": "paid",
    "tran_ref": "TST2104500076080",
    "tran_status": "A",
    "tran_status_msg": "Authorised"
}


Otherwise, it will return the invoice status only, as shown below:

{
    "invoice_status": "pending"
}






   

⌂ 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.