Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.
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 what Paytabs Invoices is? solutions article.
In this article, we will walk you through the valid way to change the status of any given invoice to be canceled using the mentioned endpoint. We highly recommend that you and your team check the "Step 3.1.4 - Invoices | Payment Workflow" solution article first to understand the business/logic this integration type relay on
In this article, you will be going to know about:
- The Endpoint and Related Postman Collection
- How to cancel any given invoice?
- The Minimum Required Parameters
The Endpoint and Related Postman Collection
In this tutorial, we will rely on the PayTabs invoices API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access from here. The endpoint will need to be accessed with a POST request on the below-mentioned URL
Post {{domain}}/payment/invoice/{{invoice_id}}/cancel
Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.
How to cancel any given invoice?
Once your invoice is initiated, it can be described with one of three statuses, which are "paid", "pending", or"canceled". You can read more about invoice status in our invoice status solution article. This article is dedicated to walking you through the valid way to change the status of a certain invoice using the InvoiceCancel request.
The Minimum Required Parameters
To initiate a cancel 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 request type:
via a PUT Request
In the PUT request type, we simply use a PUT request with only the {{invoice_id}}} as a parameter in the URL to cancel the status. you can find a sample request below that cancels an invoice with a given id "2075865".
via a POST Request
In the POST request type, we simply use a POST request with only the "invoice_id" and "profile_id" as payload parameters to cancel the invoice. As shown belowParameter
Data Type
Required
Purpose
INT
✔
The merchant Profile ID you can get from your PayTavs dashboard. For more information please check our How to get your account information from PT2 Dashboard? solution article.
To know more about this parameter please click here.
INT
✔
Indicates the invoice reference you want to query.
To know more about this parameter please click here.
Sample Request Payload
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 according to the request type:
via a PUT Request
Sample Response Payload
{
"message": "Invoice has been cancelled"
}⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article.
⇦ And to get familiar with the rest of the steps regarding the current step "Step 7 - Manage Transactions" kindly click here.
⇦ And to navigate to the previous step in the integration process "Step 6 - Handle the post payment responses" kindly click here.