Skip to main content

Invoice External Payment (Mark as Paid)

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 solutions article: What is PayTabs Invoice?

Invoices Payment Page integration type is suitable for merchants with PCI SAQ A or merchants does not have any PCI levels as it follows Hosted Payment page mechanism. To customize the UI of the Invoices payment page, check this article, and to know more about the Invoices Payment Page PCI DSS merchant requirements, please check this article.

The Mark as Paid feature allows merchants to manually update an invoice's status when payment is received outside the system, such as bank transfer, POS, cash, or cheque. To ensure accurate tracking, users must specify the payment method and include a brief description (e.g., cheque number or transaction reference). This helps maintain transparency and supports reconciliation of offline transactions within the invoice management workflow.

Be Aware Of

This feature is currently supported exclusively on the KSA and UAE instances.

Important

Please note that this feature is not enabled by default. To request activation, kindly send an email to [email protected], including your Profile ID and region/instance, and our team will assist you accordingly.

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. he endpoint will need to be accessed with the mentioned HTTP request via the below URL endpoint:

POST{{domain}}/payment/invoice/paid
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/paid

Required Parameters​

To make Invoice External Payment (Mark as Paid) request for an invoice, there are required parameters that need to be passed with valid information. The specification of these required parameters is clarified below according to the request type:

ParameterData TypeMinMaxRequired
profile_id
INTAccept only valid profile number.✔
The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article. To know more about this parameter please click here.
{
    "profile_id": 987654
}
invoice_currency
STRING✔
Indicates the existing invoice currency, which the customer was charged via offline payment.
{
   "invoice_currency" => "SAR"  
}
invoice_total
DECIMAL✔
Indicates the existing invoice total amount, which the customer was charged via offline payment.
{
   "invoice_total" => 1200  
}
pay_method
ENUM✔
Indicates the offline payment method used for collecting the invoice amount:
  • For Cash: cash
  • For Cheque: cheque, orchq
  • For Bank Transfer: Bank Transfer, BankTransfer, or Bank
  • For Point Of Sale: POS, or PointOfSale
{
   "pay_method": "cheque"  
}
pay_description
STRING164✔
Include relevant details (e.g., cheque number or reference)
{
   "pay_description": "Cheque number 123456789"  
}

Sample Request Payloads​

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 and mark the invoice as paid:

{
  "profile_id": "11###",
  "invoice_id": 1415964,
  "invoice_currency": "SAR",
  "invoice_total": 1000,
  "pay_method": "cheque",
  "pay_description": "Cheque number 123456789"
}

Sample Response Payloads​

The response will include the request details, along with the new transaction reference.

{
    "profile_id": 11###,
    "invoice_id": 1415964,
    "invoice_currency": "SAR",
    "invoice_total": "1000.00",
    "pay_method": "Cheque",
    "pay_description": "Cheque number 123456789",
    "tran_ref": "PTS######"
}

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 mark an existing invoice as paid, 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, businesses may settle the invoice amount through offline channels. Such as cash, cheque, bank transfer, or POS. And utilize this method to formally record the payment against the invoice.


  3. Upon submitting the request, the system will return the corresponding payment transaction reference, confirming the linkage between the invoice and the recorded offline settlement.

    {
      "profile_id": 11###,
      "invoice_id": 1415964,
      "invoice_currency": "SAR",
      "invoice_total": "1000.00",
      "pay_method": "Cheque",
      "pay_description": "Cheque number 123456789",
      "tran_ref": "PTS24163######"
    }

  4. In the meantime, the transaction would be already created on your dashboard, which you can access from your merchant dashboard.


    PayTabs mark as paid invoice

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.