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.


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 "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


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 hereThe endpoint will need to be accessed with a POST request on the below-mentioned URL


Post{{domain}}/payment/invoice



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

profile_id 

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.

tran_type 

STRING

Valid string from this list

the identification of the type of the transactionTo 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.

tran_class 

STRING

Valid string from this list

the identification of the category/class this transaction will follow, such as eCommerce, Recurring, etcTo know more about these types please check our What is the "tran_class" (transaction class)? solution article.

cart_id 

STRING

1

64

Indicates the cart/order id at the merchant end to easily relate the transaction to

cart_description 

STRING

1

128

Indicates the cart/order description at the merchant end to easily relate the transaction to

cart_currency 

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

cart_amount 

DECIMAL

0.01

9999999999.99

Indicates the amount of the  transaction the customer is about to be charged
Both min and max values are subjected to the merchant transaction limits.



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

invoice 

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.

invoice.line_items 

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.

line_items.quantity 

 

INT

1

9999999999

Indicates the purchased quantity of this invoice item.

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": 79090
"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


{
"invoice_id": 2072841,
"invoice_link": "https://secure-egypt.paytabs.com/payment/request/invoice/2072841/A8CB6A4667A444E79E868206DB76382A"
}



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:


{
"profile_id": ,
"tran_type": "sale",
"tran_class": "ecom",
"cart_currency": "AED",
"cart_amount": "9.5",
"cart_id": "cart_12345",
"cart_description": "Test Description",
"hide_shipping": true,
"customer_ref":"CUST0101",
"customer_details": {
"name": "First Last",
"email": "[email protected]",
"street1": "404, 11th st, void",
"city": "Dubai",
"country": "AE"
},
"invoice": {
"shipping_charges": 0,
"extra_charges": 0,
"extra_discount": 0,
"total": 0,
"activation_date": "",
"expiry_date": "2022-09-27T13:33:00+04:00",
"due_date": "2022-09-26T12:36:00+04:00",
"line_items": [
{
"sku": "sku",
"description": "desc",
"url": "https://www.costacoffee.ae/whats-new/flat-white",
"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
}
]
},
"callback": "",
"return": ""
}
Generic



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.


{ 
"invoice_id": 10000010001,
"invoice_link": "https://secure.paytabs.com/payment/request/invoice/1320598/C959A415A47D4E3E8F5000000AAAAABBBBCCCCADE9A01"
}
Generic



Send the Invoice via SMS


Reaching this section, your invoice is now ready to be sent to your clients. To do so, you can use your mail provider to send the generated invoices, or even you can use our invoice SMS API  to send your invoices via SMS to your clients. You can find the steps you need to send an invoice via SMS in our Send Invoices via SMS solution article.

 







⌂ 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.