Application Programmer Interface

This section applies if you are looking to have a seamless payment and design or if you have your own plan to accept payment we give you the power to build and integrate your way. For any integration concerns, contact our technical team, we will be happy to assist you.

Shop Plugin

Simply click on shopping cart system to learn about our ready-made extensions for your business' shopping cart platform and start accepting simple and secure payments from your customers. For any integration concerns, Contact our technical team, we are happy to assist you.

Documentation

Merchants will be provided with proper usage documentation for development.

API Integration

E-commerce Cart integration

Ready-made extensions for your platform to integrate directly to your website. Click on Shopping Cart system to know more about our ready-made extensions for your business Shopping Cart platform and start accepting payments. For any concerns regarding integration, contact our technical team, who will be happy to assist you.
(i.e. E-commerce shops, online stores with built-in platforms)


Integration Services

PayTabs can also help you to integrate the PayTabs API and Plug ins with your system for a very small amount. If you want us to help you with integration you can contact us

Express Checkout v3.0

PayTabs Express CheckOut is a solution that provides an efficient checkout process for online shoppers and keeps them on the merchant’s website while making a payment and even after the payment is complete


It has an option to collect the information from the checkout form present on the merchant’s website like personal information, billing address and shipping address. If your website does not support payments that include Shipping address you can customize the Express Checkout form to remove/hide these fields. Moreover, you can even use your own button image/design for the express Checkout button on your website.


Here’s a demo of what the PayTabs Express CheckOut looks like: Please use 4111111111111111 to test a non 3d secure Transaction. And use 4000000000000002 to test a 3d secure Transaction.



PayTabs Express CheckOut V3 Settings

Pre-requisites:
There are no mandatory prerequisites but to include a custom CSS file, it must be hosted on a secure HTTPS connection.
Highly recommended

All submissions of payment info using Express CheckOut are made via a secure HTTPS connection. However, in order to protect yourself from certain forms of man-in-the-middle attacks, we suggest that you also serve the page containing the payment form with HTTPS as well. This means that any page that an Express CheckOut form may exist on should start with https:// rather than just http://.

PayTabs JavaScript file should always be hosted on paytabs.com. If we make any changes or update in JavaScript file, you wont be able to receive the updates which will result in your transactions being considered as fraudulent and consequently they will be rejected.


Set up:
  • Download the PayTabs Express CheckOut Documentation. here
  • Go to https://www.paytabs.com/developers again, then go to Express CheckOut V 3.0 and copy the button code.
  • Copy the button code to the place where you want the checkout button.
  • Set up the variables according to you requirement. Do not comment any field in the button code. If you do not wish to use a certain field, kindly leave it blank.
  • You can use the test cards, to test a Transaction on your DEMO merchant account. Test cards will only give successful payment results, if your merchant account is in DEMO or TEST mode. Please do not use test cards on your LIVE PayTabs Merchant Account. This may cause your Merchant Account to be blocked or suspended.
  • Please remember that CheckOut is a FINAL step. Express checkout cannot be used for multiple products placed in the same page. It should be used as a final payment step after the checkout.

Sample Button Code for Minimal Express CheckOut

<link rel="stylesheet" href="https://www.paytabs.com/express/express.css">
<script src="https://www.paytabs.com/theme/express_checkout/js/jquery-1.11.1.min.js"></script>
<script src="https://www.paytabs.com/express/express_checkout_v3.js"></script>
<!-- Button Code for PayTabs Express Checkout -->
<div class="PT_express_checkout"></div>
<script type="text/javascript">
    Paytabs("#express_checkout").expresscheckout({
        settings:{
            secret_key: "YOUR_SECRET_KEY",
            merchant_id: "YOUR_PAYTABS_MERCHANT_ID eg 10001234",
            amount: "10.00",
            currency: "USD",
            title: "Test Express Checkout Transaction",
            product_names: "Product1,Product2,Product3",
            order_id: 25,
            url_redirect: "https://www.YOURWEBSITE.com/return_url/"
        }
    });
</script>


PayTabs require that your website where you are integrating express checkout should be the same as the website/URL registered in your PayTabs Merchant Account. The merchant can see this SITE URL on his/her dashboard, under “My Profile”.

For Demo Users:

You can edit your site URL by clicking going to “My Profile” and clicking on edit, enter your correct site URL and click on Save.

For Live Users: (Required)

You can use the website that you have submitted in the Go-Live application. If you need to edit/change the site URL, you can send a request to account manager.

Settings

The following button code should be placed on the page where you want the CheckOut button to appear. The button code has various parameters that are mandatory to achieve a successful payment via PayTabs. These parameters are passed through the settings object


Element Description Format
merchant_id Required.
Merchant ID found at the top-right corner of the Merchant Dashboard.
String.
E.g.: 100001646
secret_key Required.
SECRET Key found on the merchant dashboard > Mobile Payment > Secret Key
String.
E.g.:Mao8sdhasfyahosdap9sd
amount Required.
Amount of the products & other charges
Decimal.
Up to 3 Decimal places E.g.: 123.399
currency Required.
Currency of the amount stated. 3 character ISO currency code
String.
E.g.: BHD for Bahrain SAR for Saudi AED for UAE
title Required.
Name of the customer who requested the order
String.
32 characters E.g.: Mr. John Doe
product_names Required.
Product names linked to this order. For multiple products use comma, separated products
String.
170 characters E.g.: IPhone, Samsung S5, Samsung S4
order_id Required.
Order ID generated on merchant's Website.
String.
40 characters E.g.: Abc-5566
url_redirect Required.
Call back URL, after payment is successful. (or rejected, if enabled)
String.
E.g.: http://yourwebsite.com/
display_billing_fields Optional.
By default value is 1. If you are already collecting this information on your website, then you can hide it, but you must pass it to PayTabs in the background through the express checkout code in order for your payment to be processed.
String.
E.g.: 0 or 1
display_shipping_fields Optional.
By default value is 1. If your website does not require shipping then set this parameter to 0.
String.
E.g.: 0 or 1
display_customer_info Optional.
By default value is 1. If you are already collecting this information on your website, then you can hide it, but you must pass it to PayTabs in the background through the express checkout code in order for your payment to be processed
String.
E.g.: 0 or 1
language Optional.
Default value is en for English. If you wish to set it to Arabic, use ar.
String.
E.g.: en or ar
redirect_on_reject Optional.
In case you wish to redirect the user even if the payment is rejected then set this value to 1. By default it is 0, which means the customer is not redirected in case the payment is rejected.
String.
E.g.: 0 or 1
Iframe

If you wish to use the express checkout like an iframe instead of pop up then pass the object is_iframe inside settings object.

Object name is is_iframe. The parameters are:

Element Description Format
load Required.
This option defines the iframe load type. Two values can be passed. 'onbodyload' if merchant wishes to load iframe on page load. onbuttonclick if merchant wishes to load iframe on checkout button click.
String.
E.g.: onbodyload or onbuttonclick
show Required.
Set value as 1 in order to use express checkout like an iframe. By default it is 0.
String.
E.g.: 0 or 1
CSS Customization

If merchant wishes to pass their own CSS then use the object style inside settings object and set the following options which are mandatory. If you want to include the custom CSS file then it must be hosted on a secure HTTPS connection.

Object name is style. The parameters are:

Element Description Format
css Required.
Set the value to “custom”
String.
E.g.: custom
linktocss Required.
The URL of the CSS file hosted on an SSL Connection
String.
https://www.yourstore.com/css/style.css
Customer Information

If merchant wishes to pass their own CSS then use the object style inside settings object and set the following options which are mandatory. If you want to include the custom CSS file then it must be hosted on a secure HTTPS connection.

Object name is style. The parameters are:

Element Description Format
first_name Required.
First Name of the Customer
String.
32 characters E.g.: John
last_name Required.
Last Name of the Customer
String.
32 characters E.g.: Smith
country_code Required.
International dialing code for Phone Number of the Customer Please enter country code without ‘0’ or ‘+’
String.
E.g.: 973 for Bahrain 971 for UAE 966 for Saudi
phone_number Required.
Phone Number of the Customer
String.
Minimum 6 numbers up to 15 numbers E.g.: 3312345678
email_address Required.
Email of the customer
String.
32 characters E.g.: customer@domain.com
Billing Addresss

This option is mandatory in the code in case you set display_billing_details to 0. Otherwise your payment will not be processed In case display_billing_details is 1 then passing this object will pre-fill billing address for the Express Checkout form on your website.

Object name is billing_address. The parameters are:

Element Description Format
full_address Required.
Complete Address of the customer. Multiple address lines will be merged into one single line.
String.
40 characters E.g.: Flat 11 Building 222 Block 333 Road 444 Manama Bahrain
city Required.
Name of the billing city selected by customer
String.
50 characters E.g.: Manama
state Required.
Billing State entered by the customer
String.
32 characters E.g.: Manama 2 characters for US and Canada E.g.: if state is New York then the state field should be NY
country Required.
Country of the customer
String.
3 character ISO country code E.g.: BHR for Bahrain AED for UAE SAU for Saudi
postal_code Required.
Billing Postal code provided by the customer.
String.
From 5 to 9 characters E.g.: 12345
Shipping Address

In case display_shipping_details is 1 then passing this object will pre-fill shipping address for the Express Checkout form on your website. This option enables you to prefill the shipping address for the Express Checkout form on your website. This option is mandatory in the code in case you set display_shipping_details to 0. Otherwise your payment will not be processed.

Object name is shipping_address. The parameters are:

Element Description Format
shipping_first_name Required.
Shipping First Name of the Customer
String.
32 characters E.g.: John
shipping_last_name Required.
Shipping Last Name of the Customer
String.
32 characters E.g.: Smith
full_address_shipping Required.
Complete Address of the customer. Multiple address lines will be merged into one single line.
String.
40 characters E.g.: Flat 11 Building 222 Block 333 Road 444 Manama Bahrain
city_shipping Required.
Name of the billing city selected by customer
String.
50 characters E.g.: Manama
state_shipping Required.
Billing State entered by the customer
String.
32 characters E.g.: Manama 2 characters for US and Canada E.g.: if state is New York then the state field should be NY
country_shipping Required.
Country of the customer
String.
3 character ISO country code E.g.: BHR for Bahrain AED for UAE SAU for Saudi
postal_code_shipping Required.
Billing Postal code provided by the customer.
String.
From 5 to 9 characters E.g.: 12345
Checkout Button

This option enables you to use your own checkout button image and design for the Express Checkout buttons on your website otherwise the default button image from PayTabs is used.

Object name is checkout_button. The parameters are:

Element Description Format
width Define the width of the image you are using for your button. By default the width is set to 150px. E.g.: 150
height Define the height of the image you are using for your button. By default the height is set to 30px. E.g.: 30
img_url Define the URL of the image that you want to use as your button. By default, the image is retrieved from PayTabs E.g.: https://www.mywebsite.com/mybutton
Pay Button

This option enables you to use your own button image and design for the Express Checkout pay button on your website, otherwise the default button image from PayTabs is used.

Object name is pay_button. The parameters are:

Element Description Format
width Define the width of the image you are using for your button. By default the width is set to 150px. E.g.: 150
height Define the height of the image you are using for your button. By default the height is set to 30px. E.g.: 30
img_url Define the URL of the image that you want to use as your button. By default, the image is retrieved from PayTabs E.g.: https://www.mywebsite.com/mybutton
Sample code with all mandatory and optional parameters:

Below is the sample code with all the options.


<link rel="stylesheet" href="https://www.paytabs.com/express/express.css">
<script src="https://www.paytabs.com/theme/express_checkout/js/jquery-1.11.1.min.js"></script>
<script src="https://www.paytabs.com/express/express_checkout_v3.js"></script>
<!-- Button Code for PayTabs Express Checkout -->
<div class="PT_express_checkout"></div>
<script type="text/javascript">
    Paytabs("#express_checkout").expresscheckout({
        settings:{
            secret_key: "YOUR_SECRET_KEY",
            merchant_id: "YOUR_PAYTABS_MERCHANT_ID eg 10001234",
            amount: "10.00",
            currency: "USD",
            title: "Test Express Checkout Transaction",
            product_names: "Product1,Product2,Product3",
            order_id: 25,
            url_redirect: "https://www.YOURWEBSITE.com/return_url/",
            display_billing_fields: 1,
            display_shipping_fields: 1,
            display_customer_info: 1,
            language: "en",
            redirect_on_reject: 1,
            style:{
                css: "custom",
                linktocss: "https://www.yourstore.com/css/style.css",
            },
            is_iframe:{
                load: "onbodyload",
                show: 1,
            },

        },
        customer_info:{
            first_name: "John",
            last_name: "Smith",
            phone_number: "5486253",
            country_code: "973",
            email_address: "john@test.com"            
        },
        billing_address:{
            full_address: "Manama, Bahrain",
            city: "Manama",
            state: "Manama",
            country: "BHR",
            postal_code: "00973"
        },
        shipping_address:{
            shipping_first_name: "John",
            shipping_last_name: "Smith",
            full_address_shipping: "Manama, Bahrain",
            city_shipping: "Manama",
            state_shipping: "Manama",
            country_shipping: "BHR",
            postal_code_shipping: "00973"
        },
        checkout_button:{
            width: 150,
            height: 30,
            img_url: "https://www.YOURWEBSITE.com/image/yourimage.jpg"
        },
        pay_button:{
            width: 150,
            height: 30,
            img_url: "https://www.YOURWEBSITE.com/image/yourimage.jpg"
        }
    });
</script>

IPN Listener

PayTabs Instant Payment Notification is a messaging service that triggers a notification to the merchant of various events pertaining to PayTabs transactions, For instance: Rejected Transaction, Force Accepted Transaction, Successful Transaction etc.


It sends a notification regardless of whether it originated via Express CheckOut, PayPage or Plugins. The notifications are sent to a listener page on your merchant server, which can then receive the messages and save the information in a database or perform the required backend processing such as order fulfilment, and transaction status related information based on the message content.


Notifications will include customer shipping address and contact details as well as the status of the transaction.


This feature is available to LIVE merchants only and is usually used to update an organization’s ERP / Accounting / E-commerce systems.


The complete IPN Documentation is available here

Mobile SDK


Tokenization & Recurring Payments

PayTabs extends its solution to provide support for Tokenization and recurring Payments. Tokenization is the process of replacing sensitive data like credit card information, with unique identification symbols ​called tokens, ​that retain all the essential information about the data without compromising its security.​ A token can then be used to perform transactions without using the exact credit card details. We provide the following services in our Tokenization API:

Tokenization:

Here we accept the credit card data​ on the first transaction​ and return a token that can be used ​in future transaction without entering the credit card details .

Installments & Recurring Payments:

​ Tokenization can be used in accepting payments in installments having a fixed end date​ or to accept recurring payments that do not have a defined end date​.​ ​ The token is used to perform automatically transactions without the credit card information being entered each time.

You can find the Tokenization documentation here.