Invoice Status
An invoice is a document you send to your client after they purchase goods or services from you. It serves two main purposes: to record the sale and to request payment. For comprehensive information about PayTabs invoices, please refer to our articleWhat is PayTabs Invoice?
If you need to check the status of an invoice, you can use the query invoice status endpoint. In this manual, we’ll guide you on how to use and manage this endpoint. We strongly recommend that you and your team read theInvoices | Payment Workflowmanual first to grasp the business logic underlying this integration type
The Endpoint and Related Postman Collection
In this tutorial, we will rely on the PayTabs Status 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/invoice/{{invoice_id}}/status |
|---|
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
- UAE
- Egypt
- Oman
- Jordan
- Kuwait
- Global
https://secure.paytabs.sa/payment/invoice/{{invoice_id}}/status
https://secure.paytabs.com/payment/invoice/{{invoice_id}}/status
https://secure-egypt.paytabs.com/payment/invoice/{{invoice_id}}/status
https://secure-oman.paytabs.com/payment/invoice/{{invoice_id}}/status
https://secure-jordan.paytabs.com/payment/invoice/{{invoice_id}}/status
https://secure-kuwait.paytabs.com/payment/invoice/{{invoice_id}}/status
https://secure-global.paytabs.com/payment/invoice/{{invoice_id}}/status
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 Get Request
- Via Post 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.
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 |
|---|---|---|---|
| INT | ✔ | 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 please click here profile_id. |
| |||
| INT | ✔ | Indicates the invoice reference you want to query. To know more about this parameter please click here invoice . |
| |||
Sample Request Payloads
- Via Get Request
- Via Post Request
As mention before, for get request, you only need to pass the invoice it and the server key to API key.
For post request, you need to set as usual the API key and the profile ID in the request as shown below:
{
"profile_id": 79010,
"invoice_id": {{invoice_id}}
}
Sample Response Payloads
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"
}