Skip to main content

Cancel Invoice

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 will guide you on the correct method to change the status of any invoice to "canceled" using the specified endpoint. We strongly recommend that you and your team review theInvoices | Payment Workflowmanual first to grasp the business logic behind this integration type.

In this tutorial, we will rely on the PayTabs cancel 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:

PUT{{domain}}/payment/invoice/{{invoice_id}}/cancel
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}}/cancel

How to Cancel Invoice ?​


In order for you to start using the cancel feature, you need to follow the below simple steps:

  • Once an invoice is initiated, it is automatically assigned the "pending" status. The invoice remains in this state until it is either successfully paid, after which its status becomes "paid", or it is explicitly canceled, changing its status to "canceled".

  • This article explains the correct way to change the status of a specific invoice using the Invoice Cancel request. Please note that an invoice can only be canceled if its current status is "pending". Invoices with a status of "paid" or "canceled" cannot be canceled.

  • To perform the cancel operation, you will need the profile_id and the invoice_id. When sending the PUT request to the cancel endpoint, only the invoice_id is required in the request payload.


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:

In the PUT request type, you can cancel the status by sending a PUT request with only the { invoice_id } as a parameter in the URL. Below is a sample request that demonstrates how to cancel an invoice with the ID "2075865."

Alt text

Request & Response Payload Samples​

This section is dedicated give you a sample API request payload using the above mentioned required parameters, along with showing you the response payload received upon using the request payload.

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

As we mentioned before, you can cancel the status by sending a PUT request with only the { invoice_id } as a parameter in the URL. Below is a sample request that demonstrates how to cancel an invoice with the ID "2075865."

Alt text

Expected Flow Behavior​

To cancel a specific invoice, follow the steps below. This flow assumes that you have already initiated an invoice and received a valid invoice_id. The cancel operation only succeeds if the invoice status is "pending". Attempting to cancel invoices that are already "canceled" or "paid" will fail, check the following sections for more details on the expected behavior in such cases:


  • Initiate the cancel step by sending a request to the cancel endpoint with the invoice_id of the invoice you want to cancel. Details can be found here: Request Parameters.


  • At this stage, the response depends on the current status of the invoice:

    If the invoice is pending: Success response.

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

  • If the invoice is already canceled or paid: a 400 error is returned.

HTTP Error Responses

When attempting to cancel an invoice that is already canceled or paid, the API returns a 500 Internal Server Error.

The API responds with a 500 Internal Server Error, indicating that the invoice cannot be canceled.

{
"code": 400,
"message": "Unable to cancel invoice",
"trace": "PMNT0402.69D17E32.000C04E6"
}

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.