Skip to main content

Request: Invoice (invoice|line_items)

Warning

This parameter ONLY working with those integration types (Hosted Payment Page, and Invoices).

In the evolving landscape of online payments, precision and detailed invoicing are crucial. PayTabs introduces the invoice parameter, designed to streamline and enhance the invoicing process for users. This feature allows merchants to create detailed invoices for each transaction, ensuring a seamless and accurate payment experience.
Instead of processing transactions without clear invoicing details, the invoice parameter enables merchants to generate comprehensive invoices that include all necessary information. This clarity helps in maintaining accurate records, reducing disputes, and providing a seamless payment experience.

By understanding the key parameters such as invoice, businesses can effectively integrate this feature to cater to their operational needs and enhance the customer experience.

How this parameter could benefit you?​

The invoice parameter is essential for the accurate and efficient processing of invoices through the PayTabs API. Here’s how this parameter can benefit your business:

  • Precision in Billing: By specifying the invoice parameter, you ensure that each transaction is accurately documented, which helps in maintaining clear and precise financial records. This precision reduces the likelihood of billing errors and disputes.

  • Enhanced Customer Trust: Providing detailed and accurate invoices builds trust with your customers. When clients receive invoices that clearly reflect their transactions, it enhances their confidence in your business operations.

  • Streamlined Financial Management: Accurate invoicing simplifies your financial management processes. It ensures that your revenue tracking is precise, aiding in better financial planning and reporting.

  • Compliance and Record-Keeping: Specifying the invoice parameter helps in maintaining compliance with financial regulations and standards. It ensures that all transactions are properly documented, which is crucial for audits and financial reviews.

  • Customization and Flexibility: The invoice parameter allows for customization in billing, catering to various business models and customer needs. Whether you are billing for a one-time service or recurring payments, this parameter provides the flexibility required to manage different invoicing scenarios.

Name but a few different Businesses/Industries that can benefit from this API parameter:

  • E-commerce: Online retailers can use the invoice parameter to generate detailed invoices for their customers, ensuring accurate billing and enhancing the shopping experience.

  • Freelancers and Consultants: Independent professionals can leverage the invoice parameter to create professional invoices for their clients, streamlining their billing process and maintaining clear financial records.

  • Subscription Services: Businesses offering subscription-based services can use the invoice parameter to manage recurring billing, ensuring that customers receive accurate and timely invoices for their subscriptions.

  • Educational Institutions: Schools and training centers can benefit from the invoice parameter by generating invoices for tuition fees, course materials, and other educational services, simplifying their administrative processes.

  • Healthcare Providers: Clinics and medical practitioners can utilize the invoice parameter to bill patients for services rendered, ensuring transparency and accuracy in their financial transactions.

Limitations​

  • Mandatory Inclusion: This parameter must be included in every payment creation request. Omitting this parameter will result in the failure of the request.

  • Required Sub-Parameters: Within the invoice parameter, certain sub-parameters such as line_items are mandatory. At least one item must be included in the line_items array to successfully create an invoice.

  • Currency Consistency: The unit_cost of items within the line_items must be in the same currency as specified in the initial request parameters. This ensures consistency and accuracy in billing.

  • Date Constraints: Parameters such as activation_date, expiry_date, and due_date must follow specific date constraints. The activation_date must be after the current date, and the expiry_date must be after the activation_date. Similarly, the due_date must be after the activation_date.

  • Optional Parameters: While there are several optional parameters available (e.g., shipping_charges, extra_charges, extra_discount), their inclusion must follow the specified validation rules. Incorrect values or formats can lead to errors in the invoice creation process.

How to Use?​

In order for you to start use the invoice parameter, you kindly need to follow the below simple steps.
The parameter can be used over two different endpoints:
  • The Payment Endpoint (HPP)
  • The Invoices Endpoint
In which endpoint the payment flow vary and different for the customer to complete the payment process.

  • Within the initiation of the request payload of the payment page as mentioned in Step 3 via regardless the integration types, you will MUST use the mandatory parameter invoice within the main request payload itself as shown below. You need also to ensure that all required parameters are included and correctly formatted.

    {
        ...
        "invoice": {
            "line_items": [
                {
                    "unit_cost": 100,
                    "quantity":5,
                }
            ]
        }
        ...
    }

  • Once you post your request, you will receive a response that includes the whole invoice object along the redirect URL as well:

    {
       ...
       "redirect_url": "https://secure.paytabs.com/payment/wr/5DB410*******9769DBA2",
       "invoice": {
           "id": 3128281,
           "shipping_charges": "0",
           "extra_charges": "0",
           "extra_discount": "0",
           "total": "9.5",
           "activation_date": 0,
           "expiry_date": 0,
           "due_date": 0,
           "issue_date": 1733496740,
           "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"
               }
           ]
       },
       ....
    }

  • Finally you will need navigate/redirect your customer to the the previous mentioned link as this is crucial for your customer to proceed through the payment process. You may need to check his customer experience after in the coming Expected Payment Flow Behavior.

Parameter Specifications​

  • invoice

    Parameter
    invoice
    DescriptionThis 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.
    Data TypeOBJECT
    Required✘
    Validation RulesAt least line_items must be included.
    Sample
    {
      "invoice": {
         ... 
      }
    }
    invoice's Nested Parameters
    Nested ParameterData TypeMinMaxRequired
    lang
    		STRINGN/AN/A✘
    This is parameter will define the invoice page languages.
    {
     "invoice": { 
         "lang":"ar"    
      }
    }
    disable_edit
    		BOOLEANN/AN/A✘
    This parameter will disable editing the invoice through the merchant dashboard.
    {
     "Invoice":{
       "disable_edit": true,
        }
    }
    shipping_charges
    		DECIMAL0.019999999999.99✘
    Indicates the shipping charges that the merchant would add to the total invoice amount if he or she has shippable items.
    {
     "invoice": {
       "shipping_charges": 0
       }
    }
    extra_charges
    		DECIMAL0.019999999999.99✘
    Indicates any extra charges that the merchant would add to the total invoice amount.
    {
     "invoice": {
        "extra_charges": 0
       }
    }
    extra_discount
    		DECIMAL0.019999999999.99✘
    Indicates an extra discount that the merchant would exclude from the total invoice amount.
    {
     "invoice": {
       "extra_discount": 0
       }
    }
    total
    		DECIMAL0.019999999999.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": {
       "total": 0
       }
    }
    activation_date
    		DATEN/AN/A✘
    Indicates the invoice activation date, which will make the invoice unavailable before this date.
    {
     "invoice": {
       "activation_date":"2024-09-27T13:33:00+04:00"
      }
    }
    expiry_date
    		DATEN/AN/A✘
    Indicates the invoice expiry date which will make the invoice unavailable after this date.
    {
     "invoice": {
       "expiry_date": "2025-09-27T13:33:00+04:00"
      }
    }
    due_date
    		DATEN/AN/A✘
    Indicates the invoice due date which will make the invoice unavailable before this date.
    {
     "invoice":{
       "due_date": "2025-09-26T12:36:00+04:00"
      }
    }
    line_items
    		OBJECTN/AN/A✘
    This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.
    {
     "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_total": "0",
       "total": "0"
       }
    }
    line_items's Nested Parameters
    Nested ParameterData TypeMinMaxRequired
    unit_cost
    		DECIMAL0.019999999999.99✔
    Indicates this invoice item cost. It must be in the same currency passed already in the Initial Request Parameters.
    quantity
    		INT19999999999✔
    Indicates the purchased quantity of this invoice item.
    sku
    		STRINGN/AN/A✘
    Indicates the SKU of a certain item to be included with item details.
    description
    		STRINGN/AN/A✘
    Indicates the item description to be included with the item details.
    url
    		STRINGN/AN/A✘
    Indicates the item URL to be included with the item details.
    net_total
    		DECIMAL0.019999999999.99✘
    This parameter indicates the net price of the current item without applying tax or discount.
    discount_rate
    		DECIMAL0.019999999999.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.
    discount_amount
    		DECIMAL0.019999999999.99✘
    This parameter indicates the discount amount for the current item. This amount will be excluded.
    tax_rate
    		DECIMAL0.019999999999.99✘
    This parameter indicates the tax rate for the current item to be included in the total price of the item.
    tax_total
    		DECIMAL0.019999999999.99✘
    This parameter indicates the tax total for the current item to be included in the total price of the item.
    total
    		DECIMAL0.019999999999.99✘
    This parameter indicates the total price of the current item to be included with the item details.

Request & Response Payloads Samples​

The below sample request payload will show you how you can pass the above-mentioned required parameter, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

{
    "profile_id": "79010",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "cart_1",
    "cart_currency": "SAR",
    "cart_amount": 12.3,
    "cart_description": "Description of the items/services",
    "paypage_lang": "en",
    "customer_details": {
       "name": "FirstName LastName",
       "email": "[email protected]",
       "phone": "9771555555555",
       "street1": "street2",
       "city": "dubai",
       "state": "dubai",
       "country": "AE",
       "zip": "54321"
    },
    "shipping_details": {
        "name": "FirstName LastName",
        "email": "[email protected]",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "dubai",
        "country": "AE",
        "zip": "54321"
    },
    "invoice": {
      "line_items": [
          {
              "unit_cost": 100,
              "quantity":5
          }
      ]
    }
}

Expected Payment Flow Behavior​

  1. As mentioned above in the How to use? section, As a merchant you would initiate a payment request per the above Specifications, same as the sample codes mentioned in the samples section above.

  2. Then, you will receive a response that includes the same invoice you passed in the request payload, along with the redirect URL. This means you have initiated a correct payment request/page successfully.

    {
        .
        .
        "redirect_url": "https://secure.paytabs.com/payment/wr/5DBXXX4F5BB9C2EXXXX8249E75E3D4D8C84",
        "invoice": {
               "id": 3128281,
               "shipping_charges": "0",
               "extra_charges": "0",
               "extra_discount": "0",
               "total": "9.5",
               "activation_date": 0,
               "expiry_date": 0,
               "due_date": 0,
               "issue_date": 1733496740,
               "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"
                   }
               ]
           },
            .
        .
    }

  3. In the meantime, your invoice would be already created on your dashboard, which you can access from your merchant dashboard.
    invoice grid view

  4. Next, you should redirect your customer to this URL within 20 minutes so the payment process can be finalized.

  5. After this, your customer would proceed normally with payment by choosing the preferred payment method (if available), and providing his card information.

    Payment Page

  6. Then, he will be redirected to his issuer bank 3DS/OTP page to authenticate the used card

  7. Finally, he would be redirect to a success/error page accordingly. By this time, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.

    transaction view

    transaction view

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.