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.

  • 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

  1. Merchant initiates payment request including Schedule request. 
  2. Clickpay processes the transaction normally and if it is successful, a schedule for recurring payments will be created as per the request. 
  3. ClickPay initiates recurring payment transaction in the specified date and amount. 
  4. Clickpay notify the merchant with the recurring payment result.
In case of failed transactions, the System will not initiate any retry, the merchant need to handle from his end.


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


Posthttps://secure.clickpay.com.sa/payment/request


{
    "profile_id": 44537,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "cart_11111",
    "cart_currency": "SAR",
    "cart_amount": 1.01,
    "cart_description": "Description of the items/services",
    "paypage_lang": "en",
    "customer_details": {
        "name": "Riyas Razak",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "SA",
        "zip": "12345"
    },
        "shipping_details": {
        "name": "Riyas Razak",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "SA",
        "zip": "12345"
    },
    "agreement": {
        "agreement_description": "Test agreement",
        "agreement_currency": "SAR", /* Must match transaction request currency */
        "initial_amount": 1.01, /* Must match transaction request amount */
        "repeat_amount": 1.01,
        "final_amount": 1.01, /* Not applicable to unlimited term agreements */
        "repeat_terms": 2,
        "repeat_period": 1,
        "repeat_every": 2, /* e.g. every 1 week, or every 4 days etc */
        "first_installment_due_date": "22/05/2024" /* Cannot be on or before today */
    }
}
Generic

Sample Response after the initial 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": "TST2418600151667",
  "merchant_id": 2348,
  "profile_id": 42781,
  "cart_id": "cart_11111",
  "cart_description": "Description of the items/services",
  "cart_currency": "SAR",
  "cart_amount": "1.01",
  "tran_currency": "SAR",
  "tran_total": "1.01",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "agreement_id": 3153,
  "customer_details": {
    "name": "Riyas Razak",
    "email": "[email protected]",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "02",
    "country": "SA",
    "zip": "12345",
    "ip": "51.39.229.172"
  },
  "shipping_details": {
    "name": "Riyas Razak",
    "email": "[email protected]",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "04",
    "country": "SA",
    "zip": "12345"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G79180",
    "response_message": "Authorised",
    "acquirer_ref": "TRAN0302.6686534C.0000820A",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2024-07-04T07:46:20Z"
  },
  "payment_info": {
    "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111",
    "expiryMonth": 5,
    "expiryYear": 2025
  },
  "ipn_trace": "IPNS0302.6686534C.0000132B"
}
Generic

Sample Response after the Recurring Follow-up 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": "SFT2415409825573",
    "previous_tran_ref": "SFT2415409825504",
    "tran_type": "Sale",
    "cart_id": "Test#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "1.00",
    "tran_currency": "SAR",
    "tran_total": "1.00",
    "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "DU",
        "country": "AE"
    },
    "payment_result": {
        "response_status": "A",
        "response_code": "004643",
        "response_message": "Authorised",
        "acquirer_message": "00:Approved",
        "acquirer_rrn": "415406098173",
        "transaction_time": "2024-06-02T06:45:48Z"
    },
    "payment_info": {
        "payment_method": "MADA",
        "card_type": "Debit",
        "card_scheme": "Mada",
        "payment_description": "#### #### #### ####",
        "expiryMonth": 7,
        "expiryYear": 2025,
        "issuerCountry": "SA",
        "issuerName": "National Commercial Bank"
    },
    "serviceId": 1,
    "token": "###############",
    "parentRequest": {
        "tran_ref": "SFT2415409825504",
        "cart_currency": "SAR",
        "cart_amount": "1"
    },
    "profileId": #####,
    "merchantId": ####,
    "trace": "PMNT0301.665C46E0.00024C10"
}
Generic


Reporting

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


Follow the Steps


select the Repeat Billing section




 Select the agreement to see more info



Cancellation Of Recurring Payment


Posthttps://secure.clickpay.com.sa/payment/agreement/cancel


Request body: 

{ 
"profile_id" : {{profile_id}},
 "agreement_id":1378 
}


Response body : 


{ 

"message": "Agreement has been cancelled", 

"status": "success", 

"trace": "PMNT0101.66852C48.00005760" 

}

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.