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 billing. And you can avoid the need for periodic following-up and payment delays. Convenient for you, and convenient for your customers.

Postman Endpoint Collection
Payment Flow
Step 1: Enable Recurring Payment Mode
Step 2: Making API call for Initiating Recurring
Reporting In Dashbroad
IPN

Postman Endpoint Collection

For the purposes of this article, you will need to use the following postman endpoints collection for testing and integrating, for proceeding with this please click here.

Payment Flow

Merchant initiates payment request including Schedule request values.
Click pay sent the billing invoice to customer.
ClickPay initiates recurring billing invoice and sent to customer in the specified date and amount.
Click pay notify the merchant with the recurring payment result once customer paid.

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: [email protected] for further assistance.

Step 2: Making API call for Initiating 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: • AED • BHD • EGP • EUR • GBP • HKD • IDR • INR • IQD • JOD •JPY • KWD • MAD • OMR • PKR • QAR • 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 Both min and max values are subjected to the merchant transaction limits. To know more about this parameter please click here.

Now in order to create a Repeat 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 agreement. Find below the Additional required parameters for the Repeat Billing Agreement payment:

Parameter	Required	Purpose
agreement	✔	This object will contain the agreement parameters that will specify all the agreement details and options.
agreement_description	✔	This parameter indicates the agreement description which you can use to distinguish your agreements and you can also use it as a title for your agreement.
agreement_currency	✔	This parameter indicates the currency that this agreement will be initiated in and you need to make sure that this is the same currency that you have passed inside the cart_currency parameter and that this currency is configured in your ClickPay profile
initial_amount	✔	This parameter indicates the initial amount that you will be requesting your customer to pay in this agreement, and you need to make sure that it is the same amount as the one you passed inside the cart_amount parameter
repeat_amount	✔	This parameter indicates the repeated amount the you want to charge your customer with at the specified time intervals that you will be passing in the below parameters.
final_amount	✔	This parameter indicates if you want to charge your customer with a final amount after completing the whole agreement payments. Note that this will not be applicable to unlimited term agreements (when setting the "repeat_terms" to 0)
repeat_terms	✔	This parameter indicates the number of times you want to repeat the payment or charge your customers and here you will be repeating the charge of the amount specified in the "repeat_amount" parameter. Note that if you passed 0 to this parameter, it means that you will be initiating an open agreement that will keep charging the customer forever or until you cancel the agreement through your dashbaord.
repeat_period	✔	This parameter indicates the interval period that you want to initiate your agreement to be repeated at (days, week, month). 1 => Day 2 => Week 3 => Month
repeat_every	✔	This parameter indicates the number of times you want to pass between charging intervals,
first_installment_due_date	✔	This parameter indicates the due date for the first payment after the initial payment created once you initiate the request.

Sample Request Payload

Post	https://secure.clickpay.com.sa/payment/agreement/new

{
    "profile_id": "42781",
    "customer_ref": "123",
    "customer_details": {
        "name": "Nancy dcf",
        "email": "[email protected]",
        "street1": "404, 11th st, void",
        "city": "Dubai",
        "country": "AE"
    },
    "agreement": {
        "agreement_description": "Global_sample_01",
        "agreement_currency": "SAR",
        "billing_type"  : 1,
        "repeat_terms": 3,
        "repeat_amount": 200.00,
        "repeat_every": 2,
        "repeat_period": 2,
        "first_installment_due_date": "17-09-2024",
        "final_amount": 50.00
    }
}

Response

{
    "agreement": {
        "id": 3306,
        "description": "Global_sample_01",
        "currency": "SAR",
        "initial_amount": "0.00",
        "repeat_amount": "200.00",
        "final_amount": "50.00",
        "billing_type": 1,
        "email": "[email protected]",
        "first_installment_due_date": "17/09/2024",
        "next_due": "17/09/2024",
        "status": 200
    },
    "trace": "PMNT0302.66E7E770.000EB818"
}

Reporting

Merchant can view all created schedules, and their related transactions.

Follow the Steps

select the Repeat Billing section

Cancellation Of Recurring Payment

Post	https://secure.clickpay.com.sa/payment/agreement/cancel

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.

Recurring Billing (Invoice Email) Print