Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of whether 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.
As PayTabs invoices follow our Hosted Payment Page mechanism, it is suitable for merchants with PCI SAQ A or merchants who do not have any PCI levels. To customize the UI of the hosted payment page, check this article, and to know more about the Hosted Payment Page PCI DSS merchant requirements, please check this article.
In this article, we will walk you through how to initiate a payment request via this integration type. You will be introduced to the required parameters that need to be passed to initiate the request, along with all the possible optional parameters as well.
We highly recommend that you and your team check the "Invoices | Payment Workflow" solution article first to understand the business/logic this integration type relay on.
Furthermore, unlike the 3.2.Ɪ.Ɪ PT2 API Endpoints | Invoices | Initiating the Payment Request which is targeting the create invoice endpoint URL, this article will focus on sending the invoice parameters with targeting the Create Payment Page endpoint URL, The would change the response you are receiving from Paytabs side, the workflow, and the Payment Page user experience, so we highly recommend checking the article Hosted Payment Page | Payment Workflow for a better understanding.
In this article, you will be going to know about:
- The Endpoint and Related Postman Collection
- The Minimum Required Parameters
- The Available Optional Parameters
- Payment Workflow
- Limitations
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/request |
Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.The Minimum Required Parameters
To initiate a payment request using this integration type, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below:
Parameter | Data Type | Min | Max | Required | Purpose |
INT | Accept only valid profile number | ✔ | 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. | ||
STRING | Valid string from this list | ✔ | the identification of the type of the transaction. To know more about these types please check our What is the "tran_type" (transaction type)? solution article. To know more about this parameter please click here. | ||
STRING | Valid string from this list | ✔ | the identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article. To know more about this parameter please click here. | ||
STRING | 1 | 64 | ✔ | Indicates the cart/order id at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
STRING | 1 | 128 | ✔ | Indicates the cart/order description at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
STRING | Valid string from the following list: • AED • BHD • EGP • EUR • GBP • HKD • IDR • INR • IQD • JOD •JPY • KWD • MAD • OMR • PKR • QAR • SAR • USD
Accepts both upper- and lower-case characters | ✔ | Indicates the transaction currency, which the customer will be charged with. To know more about this parameter please click here. | ||
DECIMAL | 0.01 | 9999999999.99 | ✔ | Indicates the amount of the transaction the customer is about to be charged To know more about this parameter please click here. | |
Now in order to create a new invoice, you need - in addition to the general required above parameters - to include new parameters required specifically for the Invoices. Find below the Additional required parameters for the Invoice:
Parameter | Data Type | Min | Max | Required | Purpose |
Object | At least "line_items" must be included | ✔ | This is the main object that holds other parameters related to invoice creation. Including this in your request is considered the main flag to be treated as an Invoice creation request, not a normal hosted payment page request. To know more about this parameter please click here. | ||
Array of Objects | At least one item must be included | ✔ | This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details. To know more about this parameter please click here. | ||
line_items.unit_cost | Decimal | 0.1 | 9999999999.99 | ✔ | Indicates this invoice item cost. It must be in the same currency passed already in the Initial Request Parameters. 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.
{
"profile_id": 9876789,
"tran_type": "sale",
"tran_class": "ecom",
"cart_currency": "EGP",
"cart_amount": "9.5",
"cart_id": "cart_12345",
"cart_description": "Test Description",
"invoice": {
"line_items": [
{
"unit_cost": 9.5,
"quantity": 1
}
]
}
}Sample Response Payload
{
"tran_ref": "TST0000000000000",
"tran_type": "Sale",
"cart_id": "cart_12345",
"cart_description": "Test Description",
"cart_currency": "EGP",
"cart_amount": "9.50",
"tran_currency": "",
"tran_total": "0",
"return": "none",
"redirect_url": "https://secure-egypt.paytabs.com/payment/wr/5E61398A82E4100000000000000000004900000000000000000000C",
"invoice": {
"id": 2565755,
"shipping_charges": "0",
"extra_charges": "0",
"extra_discount": "0",
"total": "9.5",
"activation_date": 0,
"expiry_date": 0,
"due_date": 0,
"issue_date": 1687354515,
"line_items": [
{
"unit_cost": "9.5",
"quantity": "1",
"net_total": "9.5",
"discount_rate": "0",
"discount_amount": "0",
"tax_rate": "0",
"tax_total": "0",
"total": "9.5"
}
]
},
"serviceId": 2,
"profileId": 9876789,
"merchantId": 87678,
"trace": "PMNT04**.**92FC**.**005E6F"
}The Available Optional Parameters
Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, each of which empowers you with a different feature and the ability to customize your invoice payment request as much as possible it could be. The specification of these optional parameters is clarified below:
Note that there are a number of optional parameters for all the transactions request clarified in our API endpoints optional parameters solution article. Here we will walk through only the invoice optional parameters.Parameter | Data Type | Min | Max | Required | Purpose |
invoice.shipping_charges
| DECIMAL | 0.01 | 9999999999.99 | ❌ | Indicates the shipping charges that the merchant would add to the total invoice amount if he or she has shippable items. |
invoice.extra_charges
| DECIMAL | 0.01 | 9999999999.99
| ❌ | Indicates any extra charges that the merchant would add to the total invoice amount. |
invoice.extra_discount
| DECIMAL | 0.01 | 9999999999.99 | ❌ | Indicates an extra discount that the merchant would exclude from the total invoice amount. |
invoice.total
| DECIMAL | 0.01 | 9999999999.99 | ❌ | Indicates the total amount of the invoice, which equals the total price of "line_items" plus "shipping_charges" + "extra_charges" minus "extra_discount". Notes that if left as 0 or null, it will be auto-calculated. |
invoice.activation_date
| DATE | The data must be after the current day date | ❌ | Indicates the invoice activation date, which will make the invoice unavailable before this date. | |
invoice.expiry_date
| DATE | To be dated after the "activation_date" parameter. | ❌ | Indicates the invoice expiry date, which will make the invoice unavailable after this date. | |
invoice.due_date
| DATE | To be dated after the "activation_date" parameter. | ❌ | Indicates the invoice due date, which will make the invoice unavailable before this date. | |
line_items.sku | STRING | - | ❌ | Indicates the SKU of a cerin item to be included with item details. | |
line_items.description
| STRING | - | - | ❌ | Indicates the item description to be included with the item details. |
line_items.url | STRING | 255 (Valid URL) | ❌ | Indicates the item URL to be included with the item details. | |
line_items.net_total | DECIMAL | 0.01 | 9999999999.99 | ❌ | This parameter indicates the net price of the current item without applying tax or discount. |
line_items.discount_rate | DECIMAL | 0.01 | 9999999999.99 | ❌ | This parameter indicates the discount rate for the current item. The rate is a percentage value that will be multiplied by the net price of the item and will be included in the total price of the item. |
line_items.discount_amount | DECIMAL | 0.01 | 9999999999.99 | ❌ | This parameter indicates the discount amount for the current item. This amount will be excluded. |
line_items.tax_rate
| DECIMAL | 0.01 | 9999999999.99 | ❌ | This parameter indicates the tax rate for the current item to be included in the total price of the item. |
line_items.tax_total
| DECIMAL | 0.01 | 9999999999.99 | ❌ | This parameter indicates the tax total for the current item to be included in the total price of the item. |
line_items.total
| DECIMAL | 0.01 | 9999999999.99 | ❌ | This parameter indicates the total price of the current item to be included with the item details. |
Sample Invoice Request Payload
Reaching this point, hence you will be able to create a fully detailed invoice request payload using the previously clarified parameters, as shown in the below sample request payload:
Sample Invoice Response Payload
Once the invoice request is validated and initiated, you will receive the following response, which you will need to complete the invoice payment workflow clarified before. The response will include two parameters, the "invoice_id," which refers to the reference of the created invoice, and the other one is the "invoice_link," which is the link of your created invoice which you will share with your customer.
Payment Workflow
,In this part we will clarify the payment workflow that will be done based on following the above. Below, you will see the behavior that will be experienced from both the merchant and the customer side.
Customer Experience
The customer would be redirected to the redirect_url that comes within the response, The Payment Page would be like the following figure
You can notice it's identical to the Payment Page created without the invoice parameter, however, this Payment page would have the "view invoice" button, which by tapping it it will show the invoice details as the following figure.
Merchant Experience (Paytabs Dashboard)
In Paytabs Dashboard you can find the Invoice once it's created with the status "Pending" as the following figure.
Also, you can find it with the status updated "Paid" once the customer made the payment.
And sure a new transaction would be created as the following figure:
Limitations
As mentioned earlier, the created invoice via the create payment page endpoint URL differs from the invoice created using the create invoice endpoint URL, In addition to what was mentioned earlier on the workflow, there are also limitations on the usage:
- The Payment Page expires after 20 Minutes of the creation.
- You will not be able to cancel it as in normal invoices.
- You will not be able to send it by SMS as in normal invoices.
- You will not be able to download it via PDF
⌂ 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 previous step "Step 2 - Configure the integration method" kindly click here.
⇦ And to get familiar with the rest of the steps regarding the current step "Step 3 - Initiating the payment" click here.
⇨ And to navigate to the next step in the integration process "Step 4 - Accepting the payment" kindly click here.