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.

The user_defined parameters allow merchants to attach their own custom information to a transaction. These fields are designed to help you store internal references, identifiers, tracking information, or any additional business-specific data that may be useful for reconciliation, reporting, system integrations, and transaction management.

Since PayTabs returns these values in the transaction final response, they provide a convenient way to associate payment records with your internal systems and workflows.

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

How this parameter could benefit you?​


  • Return Additional Metadata: The user_defined object allows you to pass additional information related to the transaction that is not covered by the standard request parameters. This can be useful for storing internal references, customer identifiers, order metadata, or any custom values that you want to receive back in transaction responses and callback notifications.

  • Simplify Transaction Reconciliation: By attaching your own business-specific data to the transaction, you can easily identify and reconcile transactions within your internal systems without relying solely on the standard PayTabs transaction details.

  • Maintain Context Across Payment Flows: The values provided within the user_defined object are preserved and returned in supported responses, allowing your application to maintain transaction context throughout the payment lifecycle.

Limitations​

  • Field Limit: The user_defined object supports up to 8 user-defined fields. Any additional fields beyond the supported limit may not be processed.

  • Callback Support Only: The user_defined values are returned as part of the callback notification response, allowing you to receive your custom metadata alongside the transaction details. But not returned in the return URL response after the payment is completed.

  • Query Transaction API:The user_defined object is returned when querying a transaction using the Transaction Reference. However, when querying a transaction using the Cart ID, the user_defined values are not included in the response.

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​

  • user_defined

    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 Show Nested Parameters
    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

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.