PayTabs Support Portal

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 
• Usage Workflow
  • Sample Request Payload
  • Sample Response Payload

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: line_items.unit_cost
     

  The Parameter Tag/Name	line_items.unit_cost
  JSON Example	{ "invoice": { "line_items": [ { "unit_cost": 9.5, } ] } }
  Data Type	Decimal
  Required	✔
  Purpose	Indicates this invoice item cost. It must be in the same currency passed already in the Initial Request Parameters.
  Min	0.1
  Max	9999999999.99
  Validation rules	Decimal numbers only

  
  
  
  

• Parameter: line_items.quantity
     

  The Parameter Tag/Name	quantity
  JSON Example	{ "invoice": { "line_items": [ { "quantity": 1 } ] } }
  Data Type	INT
  Required	✔
  Purpose	Indicates the purchased quantity of this invoice item.
  Min	1
  Max	9999999999
  Validation rules	Decimal numbers only

  
  

• Parameter: invoice.shipping_charges 
  
  

{   "invoice": {        "shipping_charges": 0     }}

• Parameter: invoice.extra_charges

{  "invoice": {        "extra_charges": 0   }}

• Parameter: invoice.extra_discount

{    "invoice": {        "extra_discount": 0   }}

• Parameter: invoice.total

{    "invoice": {        "total": 0    }}

• Parameter: invoice.activation_date

{    "invoice": {        "activation_date":"2022-09-27T13:33:00+04:00"   }}

• Parameter: invoice.expiry_date

{    "invoice": {        "expiry_date": "2022-09-27T13:33:00+04:00"    {}

• Parameter: invoice.due_date

{"invoice":{          "due_date": "2022-09-26T12:36:00+04:00",  }}

• Parameter: line_items.sku

{"invoice":"line_items":[  {        "sku": "sku",  }     ]}

• Parameter: line_items.description

{"invoice":"line_items":[  {      "description": "desc"  }     ]}

• Parameter: line_items.url

{"invoice":"line_items":[  {     "url": "https://www.costacoffee.ae/whats-new/flat-white"  }     ]}

• Parameter: line_items.net_total

{"invoice":"line_items":[  {      "net_total": 9.5  }     ]}

• Parameter: line_items.discount_rate

{"invoice":"line_items":[  {    "discount_rate": 0  }     ]}

• Parameter: line_items.discount_amount

{"invoice":"line_items":[  {    "discount_amount": 0  }     ]}

• Parameter: line_items.tax_rate

{"invoice":  "line_items":[    {     "tax_rate": 0,    }       ]}

• Parameter: line_items.tax_total

{"invoice":  "line_items":[    {     "tax_total": 0,    }       ]}

• Parameter: line_items.total

{"invoice":  "line_items":[    {     "total": 9.5    }       ]}

• Parameter: notifications

{"invoice":                     "notifications":{                                                                     },}

• Parameter: notifications.emails

{"invoice":                     "notifications":{                               "emails":["[email protected]","[email protected]"]                                      },}

• Parameter: notifications.phone_numbers

{"invoice":                     "notifications":{                            "phone_numbers":["+2010101010"]                                      },}

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

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

line_items.quantity    line_items.tax_total