Skip to main content

Request: Invoice (invoice)

The "Invoice" is one of the required parameters that you must use while initiating any invoice request. It represents the merchant's profile, obtained from the PayTabs Merchant dashboard. It is a crucial identifier for the transaction process. Ensuring the correct profile number is provided is essential for transaction validation.

Parameter Specifications​

Parameterinvoice
Data TypeObject
Description
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.
Required✔
Sample
{
    "invoice": {
 
     ... 
 
  }
}
Object Nested Parameters
Parameter
Data Type
Required
Min
Max
lang
STRING
❌
Only “en” or “ar” is supported
This is parameter will define the invoice page languages.
disable_edit
BOOLEAN
❌
true or false
This parameter will disable editing the invoice through the merchant dashboard.
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.
extra_charges
DECIMAL
❌
0.01
9999999999.99
Indicates any extra charges that the merchant would add to the total invoice amount.
extra_discount
DECIMAL
❌
0.01
9999999999.99
Indicates an extra discount that the merchant would exclude from the total invoice amount.
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.
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.
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.
due_date
DATE
❌
To be after activation_date
Indicates the invoice due date which will make the invoice unavailable before this date.

Sample Request & Response Payloads​

Click to view the full Request Payload!
{
    "profile_id": "987###",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "SAR",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",
}
Click to view the full Response Payload!
{
"tran_ref": "TST22********159",
"tran_type": "Sale",
"cart_id": "CART#1001",
"cart_description": "Description of the items/services",
"cart_currency": "SAR",
"cart_amount": "500.00",
"return": "none",
"redirect_url": "https://secure.paytabs.sa/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}

Expected behavior​

  1. You will initiate a payment request using the guide mentioned here

  2. You will use the "profile_id" parameter according to the above Specifications

  3. Then you will receive the response payload containing the "redirect_url" meaning you have initiated a correct payment request.

  4. Finally, you should redirect your customer to this URL so the payment process can be finalized.