Skip to main content

Request/Response: User Defined (user_defined)

The "user_defined" is one of the optional parameters that you can use while initiating a payment request. It allows merchants to customize transactions by passing additional fields. These fields are included in the callback response, offering flexibility in handling transaction data.

Why You Should Use This Parameter​

This is one of the optional parameters that you can use to pass values related to your transaction/order that you can then receive these values as it is in the transaction response. This is not subjected to any PayTabs validations, and it is only subjected to your internal use.


Parameter Specifications​

Parameteruser_defined
Data TypeObject
Description
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.
Required❌
Sample
{
    "user_defined": {
        "udf1": "UDF1 Test",
        "udf2": "UDF2 Test",
        "udf3": "UDF3 Test",
        "udf4": "UDF4 Test",
        "udf5": "UDF5 Test",
        "udf6": "UDF6 Test",
        "udf7": "UDF7 Test",
        "udf8": "UDF8 Test",
        "udf9": "UDF9 Test"
    }
}
Object Nested Parameters
Parameter
Data Type
Required
Min
Max
udf1
STRING
❌
1
255
udf2
STRING
❌
1
255
udf3
STRING
❌
1
255
udf4
STRING
❌
1
255
udf5
STRING
❌
1
255
udf6
STRING
❌
1
255
udf7
STRING
❌
1
255
udf8
STRING
❌
1
255
udf9
STRING
❌
1
255

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",
        "user_defined": {
        "udf1": "UDF1 Test",
        "udf2": "UDF2 Test",
        "udf3": "UDF3 Test",
        "udf4": "UDF4 Test",
        "udf5": "UDF5 Test",
        "udf6": "UDF6 Test",
        "udf7": "UDF7 Test",
        "udf8": "UDF8 Test",
        "udf9": "UDF9 Test"
}
}
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.