Request/Response: Send Invoices (notifications)

Warning

This parameter ONLY working with those integration types (Invoice).

In the realm of making your digital transactions more easier and smoother, PayTabs offers robust solutions for sending your invoices via the Invoices APIs. This section delves into two specific methods: sending invoices via SMS or email.

By leveraging these API parameter, businesses can streamline their invoicing processes, ensuring timely and efficient payment requests. Whether opting for the immediacy of SMS or the comprehensive reach of email, these tools provide versatile options to meet diverse business needs.

The notifications parameter is used to send automated notifications to customers when an invoice is generated. This ensures that customers are promptly informed about their invoices, which can help in speeding up the payment process and improving customer satisfaction.

---

How this parameter could benefit you?

The notifications parameter offers two primary options for sending invoices to customers: via SMS and via Email. Each method has its unique advantages, allowing merchants to choose the most effective way to reach their customers.

• Sending Invoices via SMS

  • Instant Delivery: SMS notifications are delivered almost instantly, ensuring that customers receive their invoices promptly.
  
  
  • High Open Rates: SMS messages typically have higher open rates compared to emails, increasing the likelihood that customers will see and act on their invoices.
  
  
  • Convenience: Customers can access their invoices directly from their mobile devices, making it easy for them to review and pay on the go.



• Sending Invoices via Email

  • Detailed Information: Emails can include more detailed information and attachments, providing customers with all the necessary details about their invoices.
  
  
  • Branding: Merchants can manage the email address sending the invoices to customers by using his own domain via SendGrid to match their branding, enhancing the customer experience.
    
    
    You Should Know

    We highly recommend you check how you can customize the email address with your brand business domain by checking ourHow to integrate my PayTabs account with my SendGrid account?tutorial article.
  
  
  • Detailed Information: Emails can include more detailed information and attachments, providing customers with all the necessary details about their invoices.

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

• E-commerce: Online retailers can use the notifications parameter to promptly inform customers about their invoices, ensuring timely payments and improving cash flow.


• Freelancers and Consultants: Independent professionals can automate their invoicing process, reducing administrative tasks and ensuring clients are promptly notified about their payments.


• Subscription Services: Companies offering subscription-based services can use this feature to notify customers about recurring invoices, helping to maintain a steady revenue stream.


• Healthcare Providers: Clinics and medical practitioners can send invoice notifications to patients, ensuring they are aware of their payment obligations and reducing the likelihood of missed payments.


• Educational Institutions: Schools and universities can use the notifications parameter to inform students and parents about tuition fees and other charges, streamlining the payment process.


• Educational Institutions: Schools and universities can use the notifications parameter to inform students and parents about tuition fees and other charges, streamlining the payment process.


• Utility Companies: Utility providers can notify customers about their bills, ensuring timely payments and reducing the risk of service interruptions.

---

Limitations

• Maximum of Five Recipients: One limitation of the notifications parameter is that it can only send notifications to a maximum of five notifications per invoice whether via SMS or Email. This restriction might be a constraint for businesses that need to notify more than five recipients about an invoice.

---

How to Use?

In order for you to start use the notifications feature, you kindly need to follow the below simple steps:

• Within theinitiation the request payload of the invoiceyou will use the optional parameter notifications within the invoice object itself.


• Inside this optional parameter (object) notifications, you should pass one the following optional parameters (objects) as clarified in the below sample:
  
  
  be aware of

  Both emails and phone_numbers cannot be passed together inside the notifications object. If they appear together in any of the sample codes here, it is JUST for educational purposes to demonstrate all the fields.
  Send Via Email

  {
      "invoice": {
              "shipping_charges": 0,
              "extra_charges": 0,
              .
              .
              "notifications":{
                            "emails":["[email protected]","[email protected]"]
              }
  }

  Send Via SMS

  {
      "invoice": {
              "shipping_charges": 0,
              "extra_charges": 0,
              .
              .
              "notifications":{
                        "phone_numbers":["+9665123456789"]
              }
  }


• Once you post your request, you will receive a response that includes either a redirect URL, or an invoice link (depending on how you initiated it. To know moreclick here).
  
  

  "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",

  "invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8CB***************B762A",


• 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

Parameter	invoice
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.
Data Type	Object
Required	✘
Validation Rules	At least line_items must be included.
Sample	{ "invoice": { ... } }
invoice's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
lang	STRING	N/A	N/A	✔
	This is parameter will define the invoice page languages.
	{ "invoice": { "lang":"ar" } }
disable_edit	BOOLEAN	N/A	N/A	✔
	This parameter will disable editing the invoice through the merchant dashboard.
	{ "invoice": { "shipping_charges": 0 }}
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":{ "disable_edit": true, } }
extra_charges	DECIMAL	0.01	9999999999.99	✔
	Indicates any extra charges that the merchant would add to the total invoice amount.
	{ "invoice": { "extra_charges": 0 }}
extra_discount	DECIMAL	0.01	9999999999.99	✔
	Indicates an extra discount that the merchant would exclude from the total invoice amount.
	{ "invoice": { "extra_discount": 0 }}
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": { "total": 0 }}
activation_date	DATE	N/A	N/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	DATE	N/A	N/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	DATE	N/A	N/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", }}

---

Request & Response Payloads Samples

Invoices

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

be aware of

Both emails and phone_numbers cannot be passed together inside the notifications object. If they appear together in any of the sample codes here, it is JUST for educational purposes to demonstrate all the fields.

Request Sample Payload

{
    "profile_id": {{profile_id}},
    "tran_type": "sale",
    "tran_class": "ecom",
    "tokenise": 2,
    "cart_currency": SAR,
    "cart_amount": "9.5",
    "cart_id": "cart_12345_2",
    "cart_description": "Test Description",
    "hide_shipping": true,
    "customer_ref":"CUST0101",
    "invoice": {
            "shipping_charges": 0,
            "extra_charges": 0,
            "extra_discount": 0,
            "total": 0,
            "expiry_date": "2023-10-27T13:33:00+04:00",
            "due_date": "2023-10-26T12:36:00+04:00",
           "notifications":{
                "emails":["[email protected]","[email protected]"],
                "phone_numbers":["+9665123456789"]
           },
        "line_items": [
            {
                "sku": "sku",
                "description": "desc",
                "url": "https://www.domain.sa/",
                "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
            }
        ]
    }
}

Response Sample Payload

{
    "bulk_email": [
        {
            "address": "[email protected]"
        },
        {
            "address": "[email protected]"
        }
    ],
    "bulk_sms": [
            {
                "numberRequested": "+201111111211",
                "sentTo": "+20 111 111 1211"
            }
        ],
    "invoice_id": 2775626,
    "invoice_link": "https://secure-egypt.PayTabs.com/payment/request/invoice/2775626/40EAF5A43CB745B2B5C58410D4192321"
}

---

Expected Payment Flow Behavior

Invoices

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 either a redirect URL, or an invoice link (depending on how you initiated it. To know more about different ways you mayclick here).
   This means you have initiated a correct invoice payment request successfully.
   
   

   "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",

   "invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8CB***************B763A",
3. Once you received the above URL the provided recipient/s would receive as well the notifications accordingly depending on the type of notification you passed.


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


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


6. After this, your customer would proceed normally with payment by providing his card information.
   
   


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


8. 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. Only successful payments will be connected to the invoice itself in the invoice record.