We recommend this method if you are PCI certified to a minimum of SAQ A-EP. Whilst card details will not be handled by your system, the payment page is displayed from your website.


In this article you will be going to know about:



Postman Endpoint Example


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

Payment Flow


Your website will display its own card entry form; however, key fields will be managed by ClickPay gateway. You will need to include a script that replaces the sensitive card data with a payment token.

When the form is submitted, the paylib.js script file first will send the card details to ClickPay server for storage and to create a temporary payment token. Then this token is inserted into the form data before it is submitted to your server. 

After receiving the payment token details from your payment page, you must send a payment request using the transaction API. You will need to include the token details you have within the payment request itself.


Your server will not receive the sensitive card details, these will be removed from the form.



First Step: Taking Card Details


Let's assume that the following is your typical Payment Form


<form action="https://yourserver.com/payment" id="payform" method="post">
	<span id="paymentErrors"></span>  
	<div class="row">    
		<label>Card Number</label>    
		<input type="text" name="number" size="20">  
	</div>  
	<div class="row">    
		<label>Expiry Date (MM/YYYY)</label>    
		<input type="text" name="expmonth" size="2">    
		<input type="text" name="expyear" size="4">  
	</div>  
	<div class="row">    
		<label>Security Code</label>    
		<input type="text" name="cvv" size="4">  
	</div> 
	<input type="submit" value="Place order"> 
</form>


To modify this typical payment form to one that uses the ClickPay managed form, there are three simple steps you will need to follow:


  1. Include the paylib.js library within the page.
  2. Change the input fields for the sensitive card data to use ‘data-paylib’ instead of ‘name’. (*)
  3. Attach the paylib.js library to the form, you will need your client key as part of this.


(*) By removing the name from fields that holding sensitive card data (card number, expiry data and security code) this will lead that they will not be submitted to your server. 

Instead, they must have a ‘data-paylib’ attribute, which allows the ClickPay systems to identify and manage them.


Then modify your payment form to us the paylib.js script file


<script src="https://secure.clickpay.com.sa/payment/js/paylib.js"></script>
<form action="https://yourserver.com/payment" id="payform" method="post">  
	<span id="paymentErrors"></span>  
	<div class="row">    
		<label>Card Number</label>    
		<input type="text" data-paylib="number" size="20">  
	</div>  
	<div class="row">    
		<label>Expiry Date (MM/YYYY)</label>    
		<input type="text" data-paylib="expmonth" size="2">    
		<input type="text" data-paylib="expyear" size="4">  
	</div>  
	<div class="row">    
		<label>Security Code</label>    
		<input type="text" data-paylib="cvv" size="4">  
	</div>  <input type="submit" value="Place order"> 
</form> 
<script type="text/javascript"> var myform = document.getElementById('payform'); paylib.inlineForm({  'key': '-- Your client key --',  'form': myform,  'autosubmit': true,  'callback': function(response) {    document.getElementById('paymentErrors').innerHTML = '';    if (response.error) {                   paylib.handleError(document.getElementById('paymentErrors'), response);     }  } }); 
</script>

Second Step: Making Payment


With the managed form integration, the card details are transmitted to the ClickPay servers by the paylib.js library, and a temporary payment token is obtained. This token must be included in the transaction request, and the customer details must be provided as well.


Sample Request Payload

Post{{domain}}/payment/request


{
    profile_id: "58469",
    payment_token: "D2w6OKit7x63DNVvd2r1",
    tran_type: "sale",
    tran_class: "ecom",
    cart_id: "99",
    cart_currency: "SAR",
    cart_amount: "2154",
    cart_description: "cart_1111",
    return: "https://webhook.site/6a2a359b-5dfc-43c7-a803-64b55d4cf092",
    callback: "https://webhook.site/6a2a359b-5dfc-43c7-a803-64b55d4cf092",
    customer_details: {
        name: "My Name",
        email: "[email protected]",
        phone: "05xxxxxxxx",
        street1: "st1 near st2",
        city: "Riyadh",
        state: "Riyadh",
        country: "SA",
        zip: "12345",
        ip: "196.219.200.200"
    }
}

Response for non 3DS cards


In the case that the used card is non 3DS, the payment result will be returned in the API response as shown below


{
  tran_ref: "SFT2710405143217",
  tran_type: "Sale",
  cart_id: "99",
  cart_description: "Cart_1234",
  cart_currency: "SA",
  cart_amount: "2154",
  return: "https://webhook.site/6a2a359b-5dfc-43c7-a803-64b55d4cf092",
  customer_details: {
    name: "My Name",
    email: "[email protected]",
    phone: "05xxxxxxxx",
    street1: "st1 near st2",
    city: "Riyadh",
    state: "Riyadh",
    country: "SA",
    zip: "12345",
    ip: "172.16.0.1"
  },
  payment_result: {
    response_status: "A",
    response_code: "G92939",
    response_message: "Authorised",
    transaction_time: "2021-12-14T05:30:39Z"
  },
  payment_info: {
    card_type: "Credit",
    card_scheme: "Visa",
    payment_description: "4111 11## #### 1111"
  }
}


Response for 3DS cards


In this case, the used card is 3DS enrolled, the API response will return a redirect URL, which you must navigate the cardholder to, to complete his payment.


{
  tran_ref: "SFT9115206147482",
  tran_type: "sale",
  cart_id: "99",
  cart_description: "cart_1234",
  cart_currency: "SAR",
  cart_amount: "2101.00",
  return: "https://webhook.site/6a2a359b-5dfc-43c7-a803-64b55d4cf092",
  redirect_url: "https://secure.clickpay.com.sa/payment/page/3F73CB0F82E217D53E7D90213E03A86479648BBFB694FC9CF9D04B76/redirect",
  customer_details: {
    name: "My Name",
    email: "[email protected]",
    phone: "05xxxxxxxx",
    street1: "st1 near st2",
    city: "Riyadh",
    state: "Riyadh",
    country: "SA",
    zip: "12345",
    ip: "172.16.0.1"
  },
  payment_info: {
    card_type: "Credit",
    card_scheme: "Visa",
    payment_description: "4000 00## #### 0002"
  }
}