OUR SECURE AND FLEXIBLE REPEAT BILLING FEATURE
WE MAKE SETTING UP RECURRING PAYMENTS A BREEZE
Now your customers only need enter up their details once, and can take advantage of automated repeating payments. And you can avoid the need for periodic following-up and payment delays. Convenient for you, and convenient for your customers.
Step 1: Enable Recurring Payment Mode
You will need to coordinate with your ClickPay relationship manager to enable Acquirer/ Processor Tokenization and ClickPay recurring transaction option on your account first.
This is a must step. Tokenization (Recurring) will fail/declined without this step.
Please send an email to: support@clickpay.sa for further assistance.
Step 2: Making API call for Initiating Token for recurring
To initiate a payment request using this integration type, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below:
Parameter | Data Type | Min | Max | Required | Purpose |
profile_id | INT | Accept only valid profile number | ✔ | The merchant Profile ID you can get from your ClickPay dashboard. For more information please check our How to get your account information from PT2 Dashboard? solution article. To know more about this parameter please click here. | |
tran_type | STRING | Valid string from this list | ✔ | the identification of the type of the transaction. To know more about these types please check our What is the "tran_type" (transaction type)? solution article. To know more about this parameter please click here. | |
tran_class | STRING | Valid string from this list | ✔ | the identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article. To know more about this parameter please click here. | |
cart_id | STRING | 1 | 64 | ✔ | Indicates the cart/order id at the merchant end to easily relate the transaction to To know more about this parameter please click here. |
cart_description | STRING | 1 | 128 | ✔ | Indicates the cart/order description at the merchant end to easily relate the transaction to To know more about this parameter please click here. |
cart_currency | STRING | Valid string from the following list: • SAR • USD
Accepts both upper- and lower-case characters | ✔ | Indicates the transaction currency, which the customer will be charged with. To know more about this parameter please click here. | |
cart_amount | DECIMAL | 0.01 | 9999999999.99 | ✔ | Indicates the amount of the transaction the customer is about to be charged To know more about this parameter please click here. |
Now in order to create a token for Billing agreement through our APIs, you will need - in addition to the general required parameters mentioned above - to include new parameters required specific to the token. Find below the Additional required parameters for the unseduled recurring:
Parameter | Required | Purpose |
tokenise | ✔ | This parameter make the transaction to generate token |
token_type | ✔ | This parameter indicate type of token is generated |
counter | ✔ | This Parameter given a count for no:of transaction |
| total_count | ✔ | This Parameter given a total count for transaction |
Sample Request Payload for Token Creation
Initial transaction for creating Token
CIT (customer initiated transaction)
| Post | https://secure.clickpay.com.sa/payment/request |
{
"profile_id": "",
"tran_type": "sale",
"tran_class": "ecom",
"tokenise": "2",
"cart_id": "cart_44444",
"cart_currency": "SAR",
"cart_amount": 1.00,
"cart_description": "Payment with tok enabled, save card enabled",
"show_save_card": false,
"callback": "",
"return": "",
"hide_shipping": true,
"token_info": {
"tokenise": "2",
"token_type": "unscheduled",
"counter": 999,
"total_count": 999
}
}Sample Response after the Token creation via Callback/IPN
After the payment is processed by the customer, the return URL will have the raw content with the token only if the payment was processed successfully
{
"tran_ref": "SFT25062####",
"tran_type": "Sale",
"cart_id": "cart_44444",
"cart_description": "Payment with tok enabled, save card enabled",
"cart_currency": "SAR",
"cart_amount": "1.00",
"tran_currency": "SAR",
"tran_total": "1.00",
"customer_details": {
"name": "Riyas Razak",
"email": "riyaz@gmail.com",
"street1": "Saudi Arabia",
"city": "Riyadh",
"state": "01",
"country": "SA",
"zip": "12334",
"ip": "#######"
},
"payment_result": {
"response_status": "A",
"response_code": "###",
"response_message": "Authorised",
"acquirer_message": "00:Approved",
"acquirer_rrn": "####",
"transaction_time": "2025-03-03T08:09:53Z"
},
"payment_info": {
"payment_method": "MADA",
"card_type": "Debit",
"card_scheme": "Mada",
"payment_description": "4125 #### #### ####",
"expiryMonth": ##,
"expiryYear": ###,
"issuerCountry": "SA",
"issuerName": "INMA Bank"
},
"serviceId": 2,
"token": "394155BE67A3EE33C4BF92F56C8A###",
"profileId": ###,
"merchantId": ####,
"trace": "PMNT0302.######.00CC8BA0"
}Sample Request Payload for Recurring Payments
Merchant initiated transaction for making the payment with Token generated in CIT (recurring)
MIT (Merchant initiated transaction)
| Post | https://secure.clickpay.com.sa/payment/request |
{
"profile_id": 44537,
"tran_type": "sale",
"tran_class": "recurring",
"cart_id": "cart_44",
"cart_currency": "SAR",
"cart_amount": 4.00,
"cart_description": "Payment with tok enabled, save card enabled",
"token": "394155BE67A3EE33C4BF92F56C8#####", */ CIT Token received */
"tran_ref": "#####", */ CIT trans_ref */
"callback": "",
"return": "",
"token_info": {
"token_type": "unscheduled"
}Sample Response after Transaction via Callback/IPN
After the payment is processed by the customer, the return URL will have the raw content with the token only if the payment was processed successfully
{
"tran_ref": "SFT250622#####",
"previous_tran_ref": "SFT250622380####",
"tran_type": "Sale",
"cart_id": "cart_44",
"cart_description": "Payment with tok enabled, save card enabled",
"cart_currency": "SAR",
"cart_amount": "4.00",
"tran_currency": "SAR",
"tran_total": "4.00",
"customer_details": {
"name": "Riyas Razak",
"email": "riyaz@gmail.com",
"street1": "Saudi Arabia",
"city": "Riyadh",
"state": "01",
"country": "SA",
"zip": "12334"
},
"payment_result": {
"response_status": "A",
"response_code": "#####",
"response_message": "Authorised",
"acquirer_message": "00:Approved",
"acquirer_rrn": "#######",
"transaction_time": "2025-03-03T08:11:50Z"
},
"payment_info": {
"payment_method": "MADA",
"card_type": "Debit",
"card_scheme": "Mada",
"payment_description": "4125 #### #### ####",
"expiryMonth": ##,
"expiryYear": ###,
"issuerCountry": "SA",
"issuerName": "INMA Bank"
},
"serviceId": 1,
"profileId": ####,
"merchantId": ####,
"trace": "PMNT0301.####.00CC18AE"
}MIT Sample transaction View
IPNs
For each transaction processed merchant will receive an IPN (instant Payment Notification) to a specified endpoint. The IPN will contain the transaction and schedule details. In case of failed delivery, the system will retry to send the notification 4 more times.