Skip to main content

Initiating The Payment

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



In this manual, we will walk you through how to initiate a payment request via this integration type. You will be introduced to the required parameters that need to be passed to initiate the request, along with all the possible optional parameters as well. We highly recommend that you and your team check the "Payment Workflow" solution article first to understand the business/logic this configuration option relay on.


Using Managed Form. your website will display its own card entry form. However, key fields will be managed by the PayTabs gateway. You will need to include a script that replaces the sensitive card data with a payment token. Hence, there are two main parts to initiating the payment

The Usage​

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
info

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 manual.

<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 PayTabs managed form, there are three simple steps:

  1. Include the paylib.js library within the page.
POST{{domain}}/payment/js/paylib.js
Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

https://secure.paytabs.sa/payment/js/paylib.js
<script src="https://secure.paytabs.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>
  1. Change the input fields for the sensitive card data to use 'data-paylib' instead of 'name'.
info

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 PayTabs systems to identify and manage them.

<script src="https://secure.paytabs.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>
  1. Attach the paylib.js library to the form. You will need your client key as part of this.
info

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

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

info

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 PayTabs, which would be used in the next step.

Expected Payment Flow Behavior​

  1. As mentioned above in the How to use? section, As a merchant you would initiate a payment request per the above Specifications, same as the sample codes mentioned in the samples section above.

  2. Then, you will receive a response that includes redirect URL. This means you have initiated a correct payment request/page successfully.

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",
  3. Then, your customer will be redirected to his issuer bank 3DS/OTP page to authenticate the used card

  4. Finally, he would be redirect to a success/error page accordingly. And now, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.


    transaction view

    transaction view