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​

The Frontend Side

The Frontend Side​

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.com/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.com/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.com/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.

The Backend Side

The Backend Side​

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

POST{{domain}}/payment/request
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/request

Request Parameters​

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:

ParameterData TypeMinMaxRequired
profile_id
INTAccept only valid profile number.✔
The merchant Profile ID you can get from your PayTabs 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.
{
    "profile_id": 987654
}
tran_type
INT

Valid string from this enum list:

sale auth void release capture refund register		✔
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_type": "sale"
}
tran_class
STRING

Valid string from this list

ecom recurring moto		✔
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.
{
     "tran_class": "ecom"
}
cart_id
STRING164✔
Indicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
{
     "cart_id": "CART#10001"
}
cart_description
STRING1128✔
Indicates the cart/order description at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
{
     "cart_id": "CART#10001"
}
cart_currency
STRING1128✔
Indicates the transaction currency, which the customer will be charged with.
To know more about this parameter please click here.
{
     "cart_currency": "SAR"
}
cart_amount
DECIMAL0.019999999999.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.
{
     "cart_amount": 500.99
}
customer_details
Object✔
Indicates the customer details for this payment. If provided, the payment page will be prefilled with the provided data.
To know more about this parameter please click here.
{
    "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "AE",
        "zip": "12345"
    }
}
customer_details's Nested Parameters
Nested ParameterData TypeMinMaxRequired
name
STRING3128✔
email
STRINGN/AN/A✔
phone
STRINGN/AN/A✔
street1
STRING3128✔
city
STRING3128✔
state
STRING22✔
country
STRINGN/AN/A✔
zip
STRINGN/AN/A✔
payment_token
STRINGValid Token that was generated earlier with a client end request using the paylib.js✔
The payment token is exclusively used with the Managed-Form integration type to create payment requests.
{
    "payment_token": "DhDdxmft7x6nkMVzKgtk"
}

Request & Response Payload Samples​

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.

{
    "profile_id": "987654",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "USD",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",
    "customer_details":
    {
        "name": "Technical Support Team",
        "email": "[email protected]",
        "phone": "+201234567890",
        "street1": "address street",
        "city": "Cairo",
        "state": "CAI",
        "country": "EG",
        "zip": "45555",
        "ip": "1.1.1.1"
    },
    "payment_token": "Dh4r8Jwt7x6tPMVzKgtk"
}

Expected Payment Flow Behavior​

  1. As mentioned above in the Frond-end Side section ( integration payment Form), As a merchant you would initiate a payment request per the above Specifications,including the Payment_token you will receive ,same as the sample codes mentioned in the samples section above.

  2. Card Authentication Check
    • If the card is not 3D Secure (3DS), the payment will proceed immediately without any further redirects.
    • If the card is 3D Secure, the payment request will include a, redirect URL, in the response, as the following
      • "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",
  3. Redirect to 3DS Authentication (If Applicable):
    • If the response includes a redirect URL, this means the card is 3D Secure, and the customer will be redirected to their issuer’s 3DS/OTP page to complete the authentication process
  4. Return to Merchant's Page
    • After completing the authentication, the customer will be redirected back to your return URL, where they will see the result of the payment attempt

  5. Finally, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.


    transaction view

    transaction view

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.