Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages. 




This article is dedicated to the clarification of the user-defined parameters The user-defined parameters are parameters that can be passed within the Transaction API request your own "user-defined fields" up to 9 fields, and accordingly, you would receive those fields in the callback response.


We highly recommend you to check our What is the Return URL vs the Callback URL? solution article, to understand what clarified through out this article



In this article, you will be going to know:


Specifications 


The Parameter Tag/Nameuser_defined
JSON Example
{
"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"
}
}
Data TypeObject 
Required
Max Length9 Parameters 



Parameter

Type

MIN

MAX

Required

user_defined.udf1 

STRING 

1 

255 

 

user_defined.udf2 

STRING 

1 

255 

 

user_defined.udf3 

STRING 

1 

255 

 

user_defined.udf4 

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 

 



Usage Workflow


Along with the required parameters mentioned in our Step 3 - PT2 API Endpoints | Initiating the payment solution article, you may need to set the user-defined parameters  as shown below:


The "callback" URL also would be set for presentation purposes.


Sample Request Payload

   

{
"profile_id": "987654",
"tran_type": "sale",
"tran_class": "ecom",
"cart_id": "CART#1001",
"cart_currency": "USD",
"cart_amount": 500,
"cart_description": "Description of the items/services",

"callback": "https://example.com/notifications",

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


Sample Response Payload
    

{
"tran_ref": "TST2231201375482",
"tran_type": "Sale",
"cart_id": "CART#1001",
"cart_description": "Description of the items/services",
"cart_currency": "USD",
"cart_amount": "500.00",
"callback": "https://example.com/notifications",
"return": "none",
"redirect_url": "https://secure-egypt.paytabs.com/payment/page/5999B2E482E5CAB9DA050F5F4F5FB3B778E943EB84A9BEC8CAF51A94",
"serviceId": 2,
"profileId": 81784,
"merchantId": 31237,
"trace": "PMNT0403.636A77FD.000D0FD9"
}


The passed user defined will NOT be recived within the returen response, ONLY within the callback/IPN one.

The Expected Parameter Behaviors


While the payment workflow proceeds with redirecting the customer to the payment page in the below listed ordered steps, one of the following behaviors will occur:

  • The customer/cardholder would enter his card details and submit the "PAY NOW" button.
  • Usually, if the card details are correct, the customer would be redirected to the issuer bank 3DSecure page to authenticate using the card.
  • After that, the customer would be redirected to the return page.
  • Along with that, Your system would receive the callback/IPN, including the user-defined parameters.

To get the best out of this, it's highly recommended to check our How to configure Instant payment notification (IPN)  solution article.

The expected behaviors as per each type of transaction details delivery:

  • The Callback

    Only if you set a callback URL within the create payment page request, in the callback object, the user-defined would be returned within the object, as shown below:

    {
    "tran_ref": "TST2231201375473",
    "merchant_id": 31237,
    "profile_id": 81784,
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500.00",
    "tran_currency": "USD",
    "tran_total": "500.00",
    "tran_type": "Sale",
    "tran_class": "ECom",
    "customer_details": {
    "name": "Mohammed EL Rayes",
    "email": "[email protected]",
    "street1": "AAA, A, BBB",
    "city": "CCC",
    "state": "C",
    "country": "EG",
    "zip": "42121",
    "ip": "156.221.96.219"
    },
    "shipping_details": {
    "name": "Mohammed EL Rayes",
    "email": "[email protected]",
    "street1": "AAA, A, BBB",
    "city": "CCC",
    "state": "C",
    "country": "EG",
    "zip": "42121"
    },
    "payment_result": {
    "response_status": "A",
    "response_code": "G20796",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2022-11-08T15:19:56Z"
    },
    "payment_info": {
    "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111",
    "expiryMonth": 12,
    "expiryYear": 2022
    },


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


    "ipn_trace": "IPNS0004.636A739C.00023A03"
    }



    This brief response can empower you to make sure to handle the user experience according to the payment status as well as and updating the order status in your database.

                   
  • The IPN

Only if you set an IPN with the type "Default Web" in the IPN object the user-defined would be returned within the object with the same structure as on the above callback.


  • The Return Page Response

In the response on the return page, the user-defined parameters will NOT be returned.



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


In this article you will be going to know about:


Sample Request Payload

The following is a sample request using transaction API and including user-defined fields

{
"profile_id": "profile_id",
"tran_type": "sale",
"tran_class": "ecom",
"cart_id": "cart_11111",
"cart_currency": "USD",
"cart_amount": 200,
"cart_description": "Description of the items/services",
"return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
"callback": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
"user_defined": {
"udf1": "UDF1 Test1",
"udf2": "UDF2 Test2",
"udf3": "UDF3 Test3",
"udf4": "UDF4 Test4",
"udf5": "UDF5 Test5",
"udf6": "UDF6 Test6",
"udf7": "UDF7 Test7",
"udf8": "UDF8 Test8",
"udf9": "UDF9 Test9"
}
}

Sample Response Payload (Callback)

{
"tran_ref": "TST2111000149148",
"merchant_id": 3469,
"profile_id": 65945,
"cart_id": "cart_11111",
"cart_description": "Description of the items/services",
"cart_currency": "USD",
"cart_amount": "200.00",
"tran_currency": "USD",
"tran_total": "200.00",
"tran_type": "Sale",
"tran_class": "ECom",
"customer_details": {
"name": "first last",
"email": "[email protected]",
"phone": "0522222222",
"street1": "address street",
"city": "dubai",
"state": "DU",
"country": "AE",
"ip": "196.219.145.121"
},
"payment_result": {
"response_status": "A",
"response_code": "G08429",
"response_message": "Authorised",
"cvv_result": " ",
"avs_result": " ",
"transaction_time": "2021-04-20T08:47:09Z"
},
"payment_info": {
"payment_method": "Visa",
"card_type": "Credit",
"card_scheme": "Visa",
"payment_description": "4111 11## #### 1111",
"expiryMonth": 11,
"expiryYear": 2023,
"IssuerCountry": "",
"IssuerName": ""
},
"user_defined": {
"udf1": "UDF1 Test1",
"udf2": "UDF2 Test2",
"udf3": "UDF3 Test3",
"udf4": "UDF4 Test4",
"udf5": "UDF5 Test5",
"udf6": "UDF6 Test6",
"udf7": "UDF7 Test7",
"udf8": "UDF8 Test8",
"udf9": "UDF9 Test9"
}
}