An invoice is a document you send to your client after purchasing goods or services from you, 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.




In this article, we will learn more about the User-defined parameters in invoices. In addition to the Invoices APIs mandatory and optional parameters, the User Defined Parameters are a set of parameters you can define on the Paytabs dashboard to be used within the Invoices APIs requests, The result of using such parameters is to be found on the Generated Invoice PDF, in addition to be shown up on the user-defined parameters on the callback/IPNs.


For better understanding, You may need to check the article Request Parameters | Pre-Defiend/Custom User Parameters (user_defined)



In this article you going to learn about:


Customize User-Defined Parameters' Labels


Kindly note that the below customization will be displayed ONLY in the PDF form. You can download your Invoice as a PDF from the merchant dashboard or by following the steps mentioned here.


The User Defined Parameters can be created using your Paytabs Dashboard following the below steps:


1. From the Navigation menu go to "Profile" then tap on the edit button next to "Custom invoice label"


2. After that, You can create up to 9 User-defined Fields, Also you can set it to be mandatory or to be displayed by turning the checkbox next to the parameter either ON or OFF.


3. Once you finish customizing the labels, this label along with the user-defined value sent in the request payload, will be displayed in the Invoice PDF as shown below:



Kindly note that whenever you customize field, the new lable will be shown in the old invoices if downloaded via PDF again.



Usage Workflow


Your system would create the invoice by making a create invoice request, adding the user_defined object including the user-defined parameter as specified on the document Request Parameters | user_defined


Specifications



Parameter 

Data Type 

Min 

Max

Required 

Purpose 

user_defined 

Object

-

-

✔

For more customizations, you can pass to the Transaction API request your own "user-defined fields" up to 9 fields, and accordingly, you would receive those fields in the callback response. 

To know more about this parameter please click here

user_defined.udf1  

STRING

1

255

❌

user_defined.udf2  

STRING

1

255

❌

user_defined.udf3  

STRING

1

255

❌

user_defined.udf3  

STRING

1

255

❌

user_defined.udf5  

STRING

1

255

❌

user_defined.udf6  

STRING

1

255

❌

user_defined.udf7  

STRING

1

255

❌

user_defined.udf8  

STRING

1

255

❌

user_defined.udf9  

STRING

1

255

❌





Sample Request Payload

{
    "profile_id": {{profile_id}},
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_currency": "EGP",
    "cart_amount": "9.5",
    "cart_id": "cart_12345",
    "cart_description": "Test Description",
    "invoice": {
        "line_items": [
            {
                "unit_cost": 9.5,
                "quantity": 1
            }
        ]
    },

    "user_defined": {
         "udf1": "ISID#10000012"
    }

}


Your system would receive the response with invoice_id, and invoice_link to send it to the customer.


Sample Response Payload


{
    "invoice_id": 27***33,
    "invoice_link": "https://secure-egypt.paytabs.com/payment/request/invoice/2781533/8D755325***************022E0116"
}


Finally, once the invoice is paid successfully, you will be able to see the customized label along with the value sent in the payload in the PDF invoice. Also, you will be receiving these parameter values in the IPN response.