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.

Managed Form integration type is suitable for merchants with PCI SAQ A-EP. To know more about the Hosted Payment Page PCI DSS merchant requirements, please check this article.

In this article, we will go through how to handle the Frontend (JS), submit the payment request, ensuring that your code fulfills the Frontend requirements and workflow. We highly recommend that you and your team check our "3.1.2 - PT2 API Endpoints | Payment workflow | Managed Form" solution article first to understand the business/logic this configuration option relay on.

This is Part one of the two parts of understanding how to initiate a payment request via Managed Form integration type as clarified in our Step 3.2.2 Managed Form | Initiating the Payment Request solution article:

In this article you will be going to know about:

The Endpoint and Related Postman Collection

In this tutorial, we will rely on the ClickPay Hosted Payment Page API Endpoint, mentioned on ClickPay API endpoints postman collection, which you can access from here. The endpoint will need to be accessed with a POST request on the below-mentioned URL

Post	{{domain}}/payment/request

Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.

Frontend Request Requirements

These are the requirement required from the website (The origin requester) using the managed form:

Should be a valid passable URL
Should be an HTTPS scheme
The hostname should contain a domain that has at least one dot in it (so not localhost)
Should not contain ".." or "/"
Should not be any path component

Not fulfilling the above requirements may result facing the error 'Access to XMLHttpRequest has been blocked by CORS policy'

Implementing the Payment Form

Most probably, you will have a payment form that looks like the following form, which we will use for the purpose of this solution article.

<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:

1. Include the paylib.js library within the page.

Make sure to use the paylib.js file from clickpay server according to your endpoint, since each region has its own endpoint, make sure to check the endpoint your merchant profile attached to.
more details on 
What is my (Region)/(endpoint URL)?

<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" 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>

2. Change the input fields for the sensitive card data to use 'data-paylib' instead of 'name'.

By removing the name from fields holding sensitive card data (card number, expiry data and security code) it means 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.

<script src="https://secure.clcikpay.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>

3. Attach the paylib.js library to the form. You will need your client key as part of this.

To get your client key check the article How to get my Authentication/Integration/API Key

<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': 'CP****-****6M-6V****-****NM',
  'form': myform,
  'autoSubmit': true,
  'callback': function(response) {
    document.getElementById('paymentErrors').innerHTML = '';
    if (response.error) {             
      paylib.handleError(document.getElementById('paymentErrors'), response); 
    }
  }
});
</script>

When the form is submitted, paylib.js first sends the card details to the ClickPay server for storage and to create a temporary payment token. This token is then inserted into the form data before it is submitted to your server.

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

At the end of these steps, your server would receive a "token", which would be a part of the initiate the request that would be sent from your server side to ClickPay, which would be used in the next step.

⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article. 

⇦ And to get familiar with the rest of the steps regarding the previous step "Step 2 - Configure the integration method" kindly click here.

⇦ And to get familiar with the rest of the steps regarding the current step "Step 3 - Initiating the payment" click here. 

⇨ And to navigate to the next step in the integration process "Step 4 - Accepting the payment" kindly click here.

3.2.1 Managed Form APIs | Initiating the Payment Request | Frontend Side Print

The Endpoint and Related Postman Collection

Frontend Request Requirements

Implementing the Payment Form

Related Articles