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.


This article is dedicated to the clarification of the invoice (invoice) parameter. "invoice" is the mandatory parameter and the unique parameter for the invoice request. The "invoice" parameter is an object parameter that contains all the specifications parameters for the invoice request. Find below the specifications for both the required invoice-included parameters and the optional too.


In this article, you will be going to know:


Specifications 

Along with the required parameters mentioned in our Step 3 - PT2 API Endpoints | Initiating the Parameter:payment solution article, you will need to set the "invoice" object in your request payload. Find below the specifications for the "invoice" object type parameter and the "invoice" sub-parameters specifications. Note that part of these parameters is required and the other part is optional.


 

  • Parameter: invoice 
      

    The Parameter Tag/Nameinvoice
    JSON Example
    {
    "invoice": { }
    }
    Data TypeObject
    Required
    PurposeThis 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.
    Validation rules At least "line_items" must be included.


  • Parameter: invoice.lang
      

    The Parameter Tag/Namelang
    JSON Example
    {
    "invoice": {

    "lang":"ar"


    }
    }
    Data Typestring
    Required
    X
    PurposeThis is the parameter will define the invoice page langues
    Validation rulesOnly “en” or “ar” is supported


  • Parameter: invoice.disable_edit

     

    The Parameter Tag/Namedisable_edit
    JSON Example
    {
    
       "Invoice":{
    
          "disable_edit": true,
    
         }
    
    }

    Data Typeboolean
    Required
    X
    PurposeThis parameter will disable editing the invoice through the merchant dashboard.
    Validation rulestrue or false



  • Parameter: invoice.line_items
      

    The Parameter Tag/Nameline_items
    JSON Example

    {
    "invoice": {


    "line_items": [
    {
    }
    ]
    }
    }
    Data TypeArray of Objects
    Required
    Purpose

    This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.

    Min1
    Max
    Validation rules At least one item must be included





  • Parameter: line_items.unit_cost
       

    The Parameter Tag/Nameline_items.unit_cost 
    JSON Example
    {
    "invoice": {

    "line_items": [
    {
    "unit_cost": 9.5,
    }
    ]
    }
    }
    Data TypeDecimal
    Required
    Purpose

    Indicates this invoice item cost. It must be in the same currency passed already in the Initial Request Parameters.

    Min0.1
    Max9999999999.99
    Validation rules Decimal numbers only




  • Parameter: line_items.quantity
       

    The Parameter Tag/Namequantity
    JSON Example

    {
    "invoice": {

    "line_items": [
    {

    "quantity": 1

    }
    ]
    }
    }
    Data TypeINT
    Required
    Purpose

    Indicates the purchased quantity of this invoice item.

    Min1
    Max

    9999999999

    Validation rules Decimal numbers only


  • Parameter: invoice.shipping_charges 

The Parameter Tag/Nameshipping_charges
JSON Example
{   "invoice": {        "shipping_charges": 0     }}
Generic
Data TypeDECIMAL
Required

PurposeIndicates the shipping charges that the merchant would add to the total invoice amount if he or she has shippable items.
Min0.01
Max9999999999.99
Validation Rules



  • Parameter: invoice.extra_charges


The Parameter Tag/Nameextra_charges
JSON Example
{  "invoice": {        "extra_charges": 0   }}
Generic
Data TypeDECIMAL
Required

PurposeIndicates any extra charges that the merchant would add to the total invoice amount.
Min0.01
Max9999999999.99
Validation Rules



  • Parameter: invoice.extra_discount


The Parameter Tag/Nameextra_discount
JSON Example
{    "invoice": {        "extra_discount": 0   }}
Generic
Data TypeDECIMAL
Required

PurposeIndicates an extra discount that the merchant would exclude from the total invoice amount.
Min0.01
Max9999999999.99
Validation Rules



  • Parameter: invoice.total


The Parameter Tag/Nametotal
JSON Example
{    "invoice": {        "total": 0    }}
Generic
Data TypeDECIMAL
Required

PurposeIndicates 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.
Min0.01
Max9999999999.99
Validation Rules



  • Parameter: invoice.activation_date


The Parameter Tag/Nameactivation_date
JSON Example
{    "invoice": {        "activation_date":"2022-09-27T13:33:00+04:00"   }}
Generic
Data TypeDATE
Required

PurposeIndicates the invoice activation date, which will make the invoice unavailable before this date.
Min
Max
Validation RulesThe data must be after the current day date



  • Parameter: invoice.expiry_date


The Parameter Tag/Nameexpiry_date
JSON Example
{    "invoice": {        "expiry_date": "2022-09-27T13:33:00+04:00"    {}
HTML
Data TypeDATE
Required

PurposeIndicates the invoice expiry date which will make the invoice unavailable after this date.
Min
Validation RulesTo be dated after the "activation_date" parameter.



  • Parameter: invoice.due_date


The Parameter Tag/Namedue_date
JSON Example
{"invoice":{          "due_date": "2022-09-26T12:36:00+04:00",  }}
HTML
Data TypeDATE
Required

PurposeIndicates the invoice due date which will make the invoice unavailable before this date.
Min
Validation RulesTo be after "activation_date"



  • Parameter: line_items.sku


The Parameter Tag/Namesku
JSON Example
{"invoice":"line_items":[  {        "sku": "sku",  }     ]}
HTML
Data TypeSTRING
Required

PurposeIndicates the SKU of a cerin item to be included with item details.
Min0
Max
Validation Rules



  • Parameter: line_items.description


The Parameter Tag/Namedescription
JSON Example
{"invoice":"line_items":[  {      "description": "desc"  }     ]}
HTML
Data TypeSTRING
Required

PurposeIndicates the item description to be included with the item details.
Min0
Validation Rules



  • Parameter: line_items.url


The Parameter Tag/Nameurl
JSON Example
{"invoice":"line_items":[  {     "url": "https://www.costacoffee.ae/whats-new/flat-white"  }     ]}
HTML
Data TypeSTRING
Required

PurposeIndicates the item URL to be included with the item details.
Min
Max255 
(Valid URL) 
Validation Rules



  • Parameter: line_items.net_total


The Parameter Tag/Namenet_total
JSON Example
{"invoice":"line_items":[  {      "net_total": 9.5  }     ]}
HTML
Data TypeDECIMAL
Required

PurposeThis parameter indicates the net price of the current item without applying tax or discount.
Min0.01
Max9999999999.99
Validation RulesDecimal values only



  • Parameter: line_items.discount_rate


The Parameter Tag/Namediscount_rate
JSON Example
{"invoice":"line_items":[  {    "discount_rate": 0  }     ]}
HTML
Data TypeDECIMAL
Required

PurposeThis 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.
Min0.01
Max9999999999.99
Validation RulesDecimal values only



  • Parameter: line_items.discount_amount


The Parameter Tag/Namediscount_amount
JSON Example
{"invoice":"line_items":[  {    "discount_amount": 0  }     ]}
Generic
Data TypeDECIMAL
Required

PurposeThis parameter indicates the discount amount for the current item. This amount will be excluded.
Min0.01
Max9999999999.99
Validation RulesDecimal values only



  • Parameter: line_items.tax_rate


The Parameter Tag/Nametax_rate
JSON Example
{"invoice":  "line_items":[    {     "tax_rate": 0,    }       ]}
HTML
Data TypeDECIMAL
Required

PurposeThis parameter indicates the tax rate for the current item to be included in the total price of the item.
Min0.01
Max9999999999.99
Validation RulesDecimal values only



  • Parameter: line_items.tax_total


The Parameter Tag/Nametax_total
JSON Example
{"invoice":  "line_items":[    {     "tax_total": 0,    }       ]}
HTML
Data TypeDECIMAL
Required

PurposeThis parameter indicates the tax total for the current item to be included in the total price of the item.
Min0.01
Max9999999999.99
Validation RulesDecimal values only



  • Parameter: line_items.total


The Parameter Tag/Nametotal
JSON Example
{"invoice":  "line_items":[    {     "total": 9.5    }       ]}
HTML
Data TypeDECIMAL
Required
PurposeThis parameter indicates the total price of the current item to be included with the item details.
Min

0.01
Max9999999999.99
Validation RulesDecimal values only


  • Parameter: notifications


The Parameter Tag/Name

notifications 

JSON Example
{

"invoice":        
             "notifications":{
                               
                              
        },}
HTML
Data TypeOBJECT
Required
PurposeThis parameter indicates the notification options through our APIs. Using this, you will be able to send the created invoice to an array of emails or phone numbers via SMS
Validation RulesAccept two arrays only: emails[] and phone_numbers[]



  • Parameter: notifications.emails


The Parameter Tag/Name

emails 

JSON Example
{

"invoice":        
             "notifications":{
                               "emails":["[email protected]","[email protected]"]
                              
        },
}
HTML
Data TypeArray   
Required
PurposeThis parameter indicates an array of emails that the created invoice will be sent to it.
Min0 emails
Max5 emails
Validation RulesValid email format



  • Parameter: notifications.phone_numbers


The Parameter Tag/Name

phone_numbers 

JSON Example
{

"invoice":        
             "notifications":{
                            "phone_numbers":["+2010101010"]
                              
        },
}
HTML
Data TypeArray   
Required
PurposeThis parameter indicates an array of phone numbers that the created invoice will be sent to it via SMS.
Min0 phone numbers
Max5 phone numbers
Validation RulesValid phone number format



Usage Workflow


Along with the required parameters mentioned in our 3.2.4 PT2 API Endpoints | Invoices | Initiating the payment solution article, you will need to set the "invoice" as shown 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": {
        "lang": "ar",
        "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": ""
}

Sample Response Payload

   

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



line_items.quantity    line_items.tax_total