Skip to main content

Retrieve Invoice Details

An invoice is a document you provide to your client after they purchase goods or services from you. It serves to both record the sale and request payment. For detailed information about PayTabs invoices, please refer to our articleWhat is PayTabs Invoice?

After your invoice is initiated and exist, and regardless of it statuses: "paid," "pending," or "canceled." For more information on invoice statuses, please refer to our invoice status manual. This article specifically outlines the proper method for retrieving complete invoice details using the designated API endpoint. Prior to proceeding with this integration, it is strongly recommended that you and your technical team review the Invoices | Payment Workflowmanual first to grasp the business logic behind this integration type.

In this tutorial, we will rely on the PayTabs retrieve invoice details Transaction API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access fromhere.The endpoint will need to be accessed with the mentioned HTTP request via the below URL endpoint:

GET{{domain}}/payment/invoice/{invoice_id}/details
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/invoice/{invoice_id}/details

Required Parameters​

To make a retrieve invoice details request, there are required parameter/s that need to be passed with valid information. The specification of these required parameters is clarified below according to the request type:

In the GET request type, you can fetch the full invoice details by sending a GET request with only the { invoice_id } as a parameter in the URL. Below is a sample request that demonstrates how to retrieve an invoice's details with the ID "3248035".

ParameterData TypeMinMaxRequired
invoice_id
INT19999999999✘
invoice_id is one of the parameters that received from our side in the payload.

 {
   "invoice_id": "10000010001"  
 }

Sample Request Payloads​

As we mentioned before, you can retrieve the invoice details by sending a GET request with only the { invoice_id } as a parameter in the URL. Below is a sample request that demonstrates how to fetch an invoice with the ID "3248035."

Retrieve invoice via Get request.

Sample Response Payloads​

Retrieves the complete details associated with the specified invoice_id. If the invoice status is paid, the response payload will include an additional parameters transaction-specific metadata: tran_ref (transaction reference), tran_status (transaction status code), and tran_status_msg (transaction status message), providing further context about the completed payment.

{
    "invoice_details": {
        "id": 3248030,
        "lang": "en",
        "shipping_charges": "0.00",
        "extra_charges": "0.00",
        "extra_discount": "0.00",
        "total": "109.50",
        "activation_date": 0,
        "expiry_date": 1758965580,
        "due_date": 1758875760,
        "issue_date": 1750851435,
        "line_items": [
            {
                "sku": "sku",
                "description": "product/service description",
                "url": "https://www.your-store-domain.com/product-path",
                "unit_cost": "109.50",
                "quantity": "1",
                "net_total": "109.50",
                "discount_rate": "0",
                "discount_amount": "0.00",
                "tax_rate": "0",
                "tax_total": "0.00",
                "total": "109.50"
            }
        ]
    },
    "invoice_status": "pending", // "cancelled" or "paid"

    // if the status is "paid" the following parameters will return within the payload
    "tran_ref": "TST2517602100955",
    "tran_status": "A",
    "tran_status_msg": "Authorised"
}

When interacting with our API, you may occasionally encounter HTTP error responses. These errors are returned when a request cannot be successfully processed due to client-side constraints. Understanding these responses is essential for effective error handling and debugging.

HTTP Error Responses

If an invalid or not existing invoice ID has been provided, the API will respond with a 404 Not Found, indicating that this invoice ID not exist.

{
  "code": 2,
  "message": "Invoice not found",
  "trace": "PMNT0401.685BF3BB.0000B10E"
}

Expected Flow Behavior​

To retrieve the details of a specific invoice, follow the steps below. This flow assumes that you have already initiated an invoice and received a valid invoice_id.:

  1. Begin by calling the API endpoint responsible for invoice creation. Upon successful creation, the response will include a unique invoice_id. This ID is essential for all subsequent operations related to the invoice.

    {
      .
      "invoice_id": "3251338",
      .
    }
    Important

    Store the invoice_id securely in your system. It serves as the primary reference for managing the invoice via API like retrieving or updating the invoice.

  2. Once you have the invoice_id, you can retrieve the full details of the invoice at any time, regardless of its current status Pending, Paid, Expired, Overdue, or cancelled:

    {
      "invoice_details": {
          "id": 3251338,
          "lang": "en",
          "shipping_charges": "0.00",
          "extra_charges": "0.00",
          "extra_discount": "0.00",
          "total": "9.50",
          "activation_date": 0,
          "expiry_date": 1758965580,
          "due_date": 1758875760,
          "issue_date": 1751375603,
          "line_items": [
              {
                  "sku": "sku",
                  "description": "Product/Service description.",
                  "url": "https://www.your-company-domain.ae/whats-new/flat-white",
                  "unit_cost": "9.50",
                  "quantity": "1",
                  "net_total": "9.50",
                  "discount_rate": "0",
                  "discount_amount": "0.00",
                  "tax_rate": "0",
                  "tax_total": "0.00",
                  "total": "9.50"
              }
          ]
      },
      "invoice_status": "pending"
    }

  3. Additionally, if the invoice status is paid you will get the transaction details associated to this invoice.

    {
      "invoice_details": {
         ......
      },
      "invoice_status": "paid",
      "tran_ref": "TST2508202038004",
      "tran_status": "A",
      "tran_status_msg": "Authorised"
    }

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.