Request/Response: Invoice ID (invoice_id)

Warning

This parameter ONLY working with those integration types (Invoices, and Invoices(Payment Endpoint)).

In the dynamic world of digital payments, accurate tracking and reference are crucial. PayTabs introduces the invoice_id parameter, a key element designed to simplify invoice management and enhance transaction visibility. This parameter provides merchants with a unique identifier for every invoice created, ensuring precise control and easy retrieval of payment details.

Instead of relying on generic references, the invoice_id parameter empowers merchants to store, search, and manage invoices efficiently. It can be used to fetch invoice details after payment, maintain accurate records in the merchant’s database, and quickly locate transactions in the dashboard.

This functionality not only improves operational efficiency but also strengthens the overall payment experience for both merchants and customers.

---

How this parameter could benefit you?

The invoice_id parameter offers significant advantages for merchants managing multiple profiles. Here’s how it can benefit you:

• Unique Identifier: The invoice_id field is generated and returned only when an invoice is created. It remains unique for each merchant profile.


• Post-Payment Reference: This ID allows merchants to retrieve complete invoice details after a payment has been processed.


• Database Storage: Merchants can securely store the invoice_id in their database for accurate record-keeping and future use.


• Dashboard Search: The invoice_id enables quick and precise searches for invoices directly within the merchant dashboard.


• Invoice Status Tracking: The invoice_id is required to check and monitor the current status of any invoice.


• Invoice Cancellation: Merchants can cancel an invoice using its invoice_id through the appropriate endpoint.


• Invoice Editing: The invoice_id is essential when making updates or modifications to an existing invoice.


• Mark as Paid: Merchants can mark an invoice as paid by referencing its invoice_id in the relevant endpoint.


• Transaction Reference: When accessing a transaction completed through an invoice, the invoice_id will appear as a reference, ensuring clear linkage between the transaction and its corresponding invoice.

Name but a few different Businesses/Industries that can benefit from this API parameter:

• Retail & E-commerce: Use invoice_id to track orders and manage refunds.


• Food & Beverage: Link invoice_id to receipts for easy reconciliation.


• Hospitality & Travel: Track bookings and payments using invoice_id.


• Education: Manage tuition and course payments with invoice_id for reporting.


• Healthcare: Associate invoice_id with patient billing and medical service payments.


• Professional Services: Use invoice_id to manage client invoices for consulting, legal, or accounting work.


• Logistics & Transportation: Track shipment invoices and reconcile freight or delivery charges with invoice_id.

---

How to Use?

In order for you to properly handle the invoice_id parameter, you kindly need to follow the below simple steps:

• Within the initiation step of the invoice creation (Step 3), the invoice_id is a response-only field. You should normally follow the steps atInvoice | Step 3 - Initiating the payment.


• At this point, in the success case, you will receive the invoice_id in the response payload along with other details.
  
  

  {
      "invoice_id": 335XXX3,
      "invoice_link": "https://secure.paytabs.sa/payment/request/invoice/335XXXX3/2250EA0B26A34AXXXXXXX684E7FBE435",
      "trace_code": "PMNTXXX1.69XXXE04.000XXXX46"
  }


• Once you have obtained the invoice_id, this parameter becomes crucial for subsequent operations. It can be used as a request field in the following endpoints:
  
  
  • Invoice Cancel
  • Invoice Edit
  • Mark as Paid
  • Retrieve Invoice Details
  • Download an Invoice
  • Invoice Status


• Finally, ensure that you store and reference the invoice_id correctly, as it is the unique identifier required for managing the lifecycle of the invoice across all related API endpoints.

---

Parameter Specifications

• invoice_id
  
  

  Parameter	invoice_id
  Description	invoice_id is one of the parameters that received from our side in the payload. returned in the success only, it's used as a Request parameter in some management endoints ( cancel, edit , mark as paid , etc .. )
  Data Type	INT
  Required	✘
  Min	1
  Max	9999999999
  Sample	{ "invoice_id": "10000010001" }

---

Request & Response Payloads Samples

Create Invoices

At this step, the invoice_id serves as response parameter, don't expect to see it in the request.

Request Sample Payload

{
"profile_id": "123XXX",
"tran_type": "sale",
"tran_class": "ecom",
"cart_description": "Description of the items/services",
"cart_id": "Unique order reference00",
"cart_amount": 100,
"cart_currency": "SAR",
"invoice": {
    "line_items": [
        {
            "unit_cost": 100,
            "quantity":2
        }
    ]
            }
}

Response Sample Payload

{
"invoice_id": 2072841,
"invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8C678206DB76382A"
}

Manage Invoices

At the following Endpoints, the invoice_id serves as a Request Parameter required to retrieve, cancel, edit, download, check the status, or mark invoices as paid. Please refer to the solution article for detailed information about each endpoint and review the corresponding request/response examples.

• Invoice Cancel Endpoint


• Invoice Edit Endpoint


• Mark as Paid Endpoint


• Retrieve Invoice Details Endpoint


• Download an Invoice Endpoint


• Invoice Status Endpoint

---

Expected Payment Flow Behavior

Create & Pay Invoice

1. As mentioned above in the How to Use? and Parameter Specifications sections, as a merchant you will create an invoice by calling the Create Invoice endpoint , following the sample payloads in the Request & Response Payloads section.


2. On a successful creation, you receive a response that includes a unique invoice_id along with a customer-facing invoice_link.
   
   

   {
     "invoice_id": 2072841,
     "invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8C678206DB76382A"
   }


3. You can copy or share the invoice_link with your customer (via email, SMS, chat, etc.) or redirect them to it directly from your application.


4. The customer opens the invoice link and proceeds to payment by entering their card/payment details. If you configured amounts/line items, they will be shown on the invoice page.
   
   


5. The customer is then redirected to their issuer bank’s 3DS/OTP page (if applicable) to authenticate the card/payment method.


6. After authentication, the customer is redirected to a success/error page accordingly. At this stage:
   • You can see the resulting transaction on your merchant dashboard (accepted/authorized/declined), and it will be linked to the corresponding invoice_id for traceability.
   • The invoice_id can be used later to retrieve the invoice details and status, reconcile records, or manage the invoice lifecycle.
   
   
   
   

Manage Invoice (using invoice_id)

1. After capturing and storing the invoice_id from the creation response, you can use it to manage the invoice via the dedicated endpoints listed in How to Use? and Request & Response Payloads.


2. Typical operations that require invoice_id as a request parameter include:
   • Invoice Status – check current invoice state (e.g., created, pending, paid, cancelled, expired).
   • Retrieve Invoice Details – fetch all invoice metadata/line items.
   • Invoice Edit – update editable fields when the invoice is not yet paid/locked.
   • Invoice Cancel – invalidate the invoice if it is still open.
   • Mark as Paid – mark an invoice as paid (permitted scenarios only; typically for offline settlements).
   • Download an Invoice – retrieve a file version of the invoice for records/sharing.


3. Example request (Cancel Invoice):
   
   

   {
     "invoice_id": 2072841
   }
   Example response (success):
   
   

   {
       "message": "Invoice has been cancelled"
   }


4. Expected outcomes by operation:
   • Status: Returns the latest invoice state so you can drive UI flows (e.g., disable the pay button if paid/cancelled).
     ⚠️ The JSON response does not include invoice_id.
   • Retrieve Details: Returns the full invoice object (merchant reference, line items, amounts, customer data, etc.).
     ✔️ The invoice_id is also included in the response payload.
   • Edit: Updates allowed fields if the invoice is still editable (not paid/locked). Invalid edit attempts will be rejected.
     ✔️ The updated response also contains the same invoice_id.
   • Cancel: Prevents further payment attempts; theinvoice_link becomes unusable.
     ⚠️ The JSON response does not include invoice_id.
   • Mark as Paid: Sets the invoice to paid (for permitted offline settlement cases).
     ✔️ The response also includes the invoice_id for tracking.
   • Download: Generates a downloadable PDF version of the invoice.
     ⚠️ The JSON response does not include invoice_id.
     ✔️ The invoice_id is present inside the PDF document itself.

``