Skip to main content

Request/Response: User Defined (user_defined)

Warning

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

The User Defined object is one of the required parameters that you must use exclusively with the Own Form integration. It identifies the customer bank card credentials like card number and the expiration date.


Next, we can delve into the specifics of how to implement the user_defined object in your requests.

How this parameter could benefit you?​

Here are some scenarios to help you understand when to use the User Defined feature:

  • Direct handling with the customer card details: This will allow you to generate your own payment form to collect the customer bank card details.


Limitations​


  • You must be PCI certified:
    Own Form Integration Type is suitable for Merchants with a PCI certified to a minimum of SAQ D-Merchant. This is because the card details will be handled by the merchant system.
    You can know more about the PCI DSS merchant requirements for this SAQ D-Merchant level from our What is PCI DSS? and What are the Merchant Requirements? solution article..

How to Use?​

In order for you to start use the user_defined object parameter, you kindly need to follow the below simple steps:

  • Within the initiation of the request payload of the payment in Step 3 via ONLY the Own Form integration, you will use the object user_defined within the main request payload itself as shown below:

    {
       "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"
       }
    }

  • Once you post your request, you will receive a response that includes the payment_info along with a redirect URL like the following:

    {
       ...
       "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",
       "payment_info": {
               "card_type": "Credit",
               "card_scheme": "Visa",
               "payment_description": "4111 11## #### 1111"
           }
       ....
    }

  • 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 3Ds to authenticate the cardholder. You may need to check the customer experience after in the coming Expected Payment Flow Behavior.

Parameter Specifications​

  • tran_type

    Parameter
    user_defined
    DescriptionFor 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.
    Data TypeObject
    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"
        }
    }
    user_defined's Nested Parameters
    Nested ParameterData TypeMinMaxRequired
    udf1
    		STRING1255✔
    udf2
    		STRING1255✔
    udf3
    		STRING1255✔
    udf4
    		STRING1255✔
    udf5
    		STRING1255✔
    udf6
    		STRING1255✔
    udf7
    		STRING1255✔
    udf8
    		STRING1255✔
    udf9
    		STRING1255✔

Request & Response Payloads Samples​

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

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.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
                "serviceId": 2,
                "profileId": 987###,
                "merchantId": 1*****7,
                "trace": "PMN****4.63****A8.00****C4"
}

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 redirect URL. This means you have initiated a correct payment request/page successfully.

    {
        .
        .
        "redirect_url": "https://secure.paytabs.com/payment/page/52E5B6B*************B4818688",
        .
        .
    }

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

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

    Payment Page

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

  6. Finally, the customer 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
  7. Also, if you have used the callback or configured IPNIPN in the profile portal, or used the Query Transaction, then you will get the transaction details contained the user_defined object details that you have defined while initiated the transaction:
    {
        "tran_ref":"TST250290XXXXXX",
        "merchant_id":XXXXX,
        "profile_id":XXXX,
        ............
        "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"
       }
    }

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.