ClickPay 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.
TABLE OF CONTENTS
Specifications
| The Parameter Tag/Name | user_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 Type | Object |
| Required | ❌ |
| Max Length | 9 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 - 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.clickpay.com.sa/payment/page/5999B2E482E5CAB9DA050F5F4F5FB3B778E943EB84A9BEC8CAF51A94",
"serviceId": 2,
"profileId": 81784,
"merchantId": 31237,
"trace": "PMNT0403.636A77FD.000D0FD9"
}The passed user defined will NOT be received within the return 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": "My Name",
"email": "[email protected]",
"street1": "AAA, A, BBB",
"city": "CCC",
"state": "C",
"country": "SA",
"zip": "42121",
"ip": "156.221.96.219"
},
"shipping_details": {
"name": "My Name",
"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.
Samples
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": "Riyadh",
"state": "Riyadh",
"country": "SA",
"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"
}
}