Downloading an Invoice
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.This endpoint is handy once your invoice is initiated to download it via a simple GET request and empower your customers on how they can display and download a static PDF of this invoice.
The Endpoint and Related Postman Collection
In this tutorial, we will rely on the PayTabs Download Invoice API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access fromPayTabs Postman APIs Collection. The endpoint will need to be accessed with a POST request on the below-mentioned URL
| GET | {{domain}}/payment/invoice/{{InvoiceId}}/download/pdf |
|---|
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.
- KSA
- UAE
- Egypt
- Oman
- Jordan
- Kuwait
- Global
https://secure.paytabs.sa/payment/invoice/{{InvoiceId}}/download/pdf
https://secure.paytabs.com/payment/invoice/{{InvoiceId}}/download/pdf
https://secure-egypt.paytabs.com/payment/invoice/{{InvoiceId}}/download/pdf
https://secure-oman.paytabs.com/payment/invoice/{{InvoiceId}}/download/pdf
https://secure-jordan.paytabs.com/payment/invoice/{{InvoiceId}}/download/pdf
https://secure-kuwait.paytabs.com/payment/invoice/{{InvoiceId}}/download/pdf
https://secure-global.paytabs.com/payment/invoice/{{InvoiceId}}/download/pdf
Request Parameters
To initiate a a download invoice request, there are minimum required URI params that need to be passed with valid information. The specification of these required parameters is clarified below:
- The Minimum Required Parameters
In the GET invoice status, we simply use a GET request passing only the [invoice_id] as a param in the endpoint URL to get the status, find below the specifications to this param:
| Parameter | Data Type | Required | |
|---|---|---|---|
| INT | ✔ | |
| Indicates the invoice reference you want to query. To know more about this parameter pleaseclick here. | |||
| |||
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.
- Required Parameters Sample Payloads
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.
- Sample Request Payload
- Sample Response Payload
curl --location --request GET 'https://secure.paytabs.com/payment/invoice/123456/download/pdf' \
--header 'Authorization: SGJNBXXXXX-J6RNNXXXXX-2ZGWLXXXXX'
Once you follow the above steps, you will receive a PDF byte object as a response to your request, and it will contain data that looks something like the following:
The Payment Page Experience
Reaching this point, you already should have initiated your invoice indeed and just wanted to share it with your customers. Here’s how it works:
- Initiating the Request: Once you initiate an invoice request, you will receive a response that includes either a redirect URL, or an invoice link (depending on how you initiated it. To know moreclick here). This URL is crucial for guiding your customer through the payment process.
"redirect_url": "https://secure.paytabs.com/payment/page/59946B********************B4817FD4488",
"invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8CB**************868206DB76382A"
- Redirecting the Customer: You should redirect your customer to one of these URLs as you normally would in a payment transaction. This step allows the customer to complete their payment securely and efficiently. Below are the resulted payment page that your customer will be redirected to:
- Download the invoice: Using the same steps clarified in this section.
- Share the invoice: After that, you can use the object sent you earlier in the above response with the associated libraries according to your development language to read/convert it as a displayable PDF document that even can be downloaded s the following:
