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?

In this manual, we 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 a GET request on the below-mentioned URL

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

How It Works?​

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 fetching the full invoice details using the Invoice details request.


The Minimum Required Parameters​

To make a retrieve invoice details 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 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".

Retrieve invoice via Get request.

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"
}
caution

Please check the following possible HTTPs 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"
}

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.