API Documentation Version 2.0
Table of Contents 1. Overview...5 1.1 Test Merchant Account v/s Live Merchant Account...5 1.2 Target Audience...5 1.3 Assistance...6 1.4 Technical Architecture...6 2 Getting started...7 2.1 Web Service URLs...8 2.2 Definitions...8 3 Authentication...9 3.1 Request...9 3.2 Response...9 3.3 Error Codes... 10 4 Create Pay Page... 11 4.1 Request... 11 4.2 Response... 15 4.3 Response Codes... 16 4.4 Error Codes... 16 4.5 Example:... 17 5 Validate API Key... 18 5.1 Request... 18 5.2 Response... 18 5.3 Error Codes... 18 6 Verify Payment... 19 6.1 Request... 19 6.2 Response... 19 6.3 Response Codes... 20 6.4 Error Codes... 20 6.5 Example... 21 7 Expire API Key... 22 7.1 Request... 22 7.2 Response... 22 7.3 Error Codes... 22 8 REST API Call Behavior... 23 9 Response & Error Codes... 24 9.1 Response Codes... 24 2 PayTabs API Documentation V e r s i o n 2. 0
9.2 Error Codes... 24 10 Test Credit Card Numbers... 25 11 Example... 26 3 PayTabs API Documentation V e r s i o n 2. 0
Revision History Version Description of Change Date 1.0 - New Document 21/11/2013 1.1 - Added Architecture Diagram & return_url in create PayPage 24/11/2013 1.2 - Added Definitions of Terms 25/11/2013 1.3 - Added Test Cards 27/11/2013 1.4 - Added Error Code 0006 for invalid country 07/01/2014 1.5 - Added MDD (Merchant Defined Data) structure in the calls 29/01/2014 1.6 - Updated Response Code 22/06/2014 1.7 1.8 1.9 2.0 - Removed All Staging Links - Removed Service Calls section - Removed Prepare Transaction API - Added API Key in subsequent API calls to authenticate requests - Added discount and Currency Fields - Added Reference Number added create PayPage - Transaction Logs API removed - Inventory API removed - Complete Transaction API removed. - Added Examples for each call - Added full Example for API - Change of Format of Documentation - Added Test Account v/s Live Account description - Added support email address - Added updated technical Architecture Diagram - Added msg_lang to create PayPage to set language - Removed User Roles - Added constraint of 9 characters for Postcode - Changed description in paypage to products_per_title - Added a note in create PayPage example. - Improved Section Numbering - Changed all API Calls from paytabs.co to paytabs.com - Changed example to include spaces between separators - Added note to include spaces between separators - Added comments to the example code and note for test cards - Unused Response Code 1 and 3 removed from document. - Added Comment for successful transaction response code - Corrected merchant_password variable in example code - Changed description variable to product_per_title in example - Supported Platforms included - Code Syntax Highlighted 26/07/2014 27/08/2014 24/09/2014 05/01/2015 4 PayTabs API Documentation V e r s i o n 2. 0
1. Overview At PayTabs, we are committed to providing the most secure, reliable and user-friendly payment processing solutions. By partnering with us for your payment processing needs, you can be confident that payment transactions will be processed quickly and efficiently, and your customers information will be safe. You ll enjoy our easy set-up using our Plugins and easy integration with our APIs. Our twolevel fraud protection system protects transaction data throughout the payment process. With PayTabs as your payment processor, you ll benefit from the fastest, most secure, and cost-effective payment processing in the industry. PayTabs API is a RESTful resource. In order to integrate with PayTabs API, you will need the credentials of your PayTabs Merchant Account. If you do not have a merchant account, you can sign up for one here. It's important to note that the PayTabs APIs are constantly evolving, and updates are usually done every quarter, if required. PayTabs will intimate any major API change, so it s important that you check your merchant dashboard notification or e-mail, frequently to be updated. 1.1 Test Merchant Account v/s Live Merchant Account PayTabs does not offer an explicit Sandbox / Testing environment. But using a demo account, you can freely test all the functionalities and integrate our API and Plugin without any hassle. In order to move to LIVE PRODUCTION environment, you will need to activate your LIVE MERCHANT ACCOUNT by clicking on GO LIVE through your PayTabs Merchant Account. PayTabs requires some personal information, documents and other details related to your business to validate your business. Once your Merchant Account is activated, you will have been moved to the LIVE PRODUCTION environment. 1.2 Target Audience This document is intended for developers who want to write applications that interact with PayTabs.com. This document assumes that you understand general networking and programming ideas. Even though code examples are built using PHP, any programming language of your choice can be used to interact with this API. This API supports PHP and.net platforms. 5 PayTabs API Documentation V e r s i o n 2. 0
1.3 Assistance If you require assistance, please check out our Frequently Asked Questions or chat live with our support staff or email us at support@paytabs.com. 1.4 Technical Architecture 6 PayTabs API Documentation V e r s i o n 2. 0
2 Getting started Here is a listing of all the APIs provided by PayTabs. S. No. API FUNCTION API CALL 1 Authentication https://www.paytabs.com/api/authentication 2 Create PayPage https://www.paytabs.com/api/create_pay_page 3 Validate API Key https://www.paytabs.com/api/api_key_valid 4 Verify Payment https://www.paytabs.com/api/verify_payment 5 Expire API Key https://www.paytabs.com/api/logout 7 PayTabs API Documentation V e r s i o n 2. 0
2.1 Web Service URLs PayTabs does not offer an explicit Sandbox / Testing environment. But using a demo account, you can freely test all the functionalities and integrate our API and Plugin without any hassle. In order to move to LIVE PRODUCTION environment, you will need to activate your LIVE MERCHANT ACCOUNT Production Environment : https://www.paytabs.com 2.2 Definitions The following are some of the terms that are used in this document and their respective definitions. TERM Merchant Customers Banks Payment processor Masked number Issuer Bank DEFINITION PayTabs customer who will use the PayTabs system in their shops/counters. The customer that the merchant will charge. They are also called cardholders. The banks to which PayTabs will interact. The 3rd party payment gateway that PayTabs is using to capture payments The first 6 and last 4 numbers of the card number with*(asterisk in the middle) The bank which has issued the credit card being used. Settlement Bank The bank where PayTabs will settle money after clearance. 8 PayTabs API Documentation V e r s i o n 2. 0
3 Authentication This method uses the merchant_id and merchant_password to authenticate the request and receive an API Key to validate all subsequent requests. The same API Key can be used to validate multiple requests provided that the requests take place within 15 minutes. After 15 minutes the API Key will expire and a new one will have to be obtained by making the authentication call again. Authentication is the only API call that accepts merchant_id and merchant_password. The other API calls validate each request using the API Key obtained from the authentication response. PATH REQUEST METHOD PRODUCTION https://www.paytabs.com/api/authentication POST LIVE 3.1 Request Element Description Format merchant_id merchant_password The merchant s valid Username, i.e. the merchant s email address used at the time of sign up. Valid password of the Merchant s PayTabs Account. > 4 characters E.g.: foo@bar.com 6 to 64 characters E.g.: testpassword 3.2 Response Element Description Format access Status of Authentication: granted / denied E.g.: granted / denied api_key The current API Key of the merchant. This Key will expire in 15 minutes. E.g.: W87egrw8egh error_code The error code is present in the response only if there is an error. 4 characters E.g.: 0002 9 PayTabs API Documentation V e r s i o n 2. 0
3.3 Error Codes Error Code Description 001 Merchant ID and password do not match 10 PayTabs API Documentation V e r s i o n 2. 0
4 Create Pay Page This method uses the API Key obtained from the authentication API Call to validate the request. This method will accept all the parameters required to create a PayPage and then return the response as well as the link where the customer can enter the credit card information and make the payment. PATH REQUEST METHOD PRODUCTION https://www.paytabs.com/api/create_pay_page POST LIVE 4.1 Request Element Description Format api_key API Key received from authentication API call or a valid API key E.g.: Mao8sdhasfyahosdap9sd cc_first_name First Name of the Customer 32 characters E.g.: John cc_last_name Last Name of the Customer 32 characters E.g.: John phone_number Phone Number of the Customer 32 characters E.g.: 9733312345678 billing_address Complete Address of the customer. Multiple address lines will be merged into one single line. 64 characters E.g.: Flat 11 Building 222 Block 333 Road 444 Manama Bahrain 11 PayTabs API Documentation V e r s i o n 2. 0
state *** State (part of the address) entered by the customer 32 characters E.g.: Manama city Name of the city selected by customer 3-4 characters E.g.: Manama postal_code Postal code provided by the customer Up to 9 characters E.g.: 12345 country email Country of the customer Email of the customer 3 character ISO country code E.g.: BHR 32 characters E.g.: customer@domain.com amount discount Amount of the transaction which should be the total Invoice amount, the API doesn t calculate this amount from unit prices & quantity of each item Optional Discount of the transaction Decimal Up to 3 Decimal places E.g.: 123.399 Decimal Up to 3 Decimal places E.g.: 123.399 reference_no Optional Invoice reference number 11 characters E.g.: Abc-5566 *** When the country is selected as USA or CANADA, the state field should contain a of 2 characters containing the ISO state code otherwise the payments may be rejected. For other countries, the state can be a string of up to 32 characters. 12 PayTabs API Documentation V e r s i o n 2. 0
currency title Currency of the amount stated. Description or title of the transaction done by the customer 3 character ISO country code E.g.: BHD 32 characters E.g.: Order # 3321 ip_customer The client IP with which the order is placed. 16 characters E.g.: 123.123.12.2 ip_merchant Server IP where the order is coming from 16 characters E.g.: 11.11.22.22 return_url The URL to which the customer will be returned to. E.g.: http://yourwebsite.com/pa yment_completed.php address_shipping Shipping address of the customer 64 characters E.g.: Flat abc road 123 city_shipping Shipping City of the customer 32 characters E.g.: Manama state_shipping *** Shipping State of the customer 32 characters E.g.: Manama *** When the country is selected as USA or CANADA, the state field should contain a of 2 characters containing the ISO state code otherwise the payments may be rejected. For other countries, the state can be a string of up to 32 characters. 13 PayTabs API Documentation V e r s i o n 2. 0
postal_code_shipping Shipping postal code of the customer Up to 9 characters E.g.: 403129 country_shipping quantity Shipping country of the customer Quantity of a products. If multiple products then add separator. 3 character ISO country code E.g.: BHR 256 characters E.g.: 1 2 3 unit_price products_per_title ChannelOfOperations ProductCategory Unit price of the product. If multiple products then add separator. Product title of the product. If multiple products then add separator Type of Products covered by the Merchant Broad Spectrum category of the product 256 characters E.g.: 21.09 22.12 12.01 256 characters E.g.: IPhone Samsung S5 Samsung S4 32 characters E.g.: Software or Non- Physical, Physical Goods, Travel Related Services 32 characters E.g.: Electronics ProductName ShippingMethod Product names with separated Shipping method 256 characters E.g.: IPhone Samsung S5 Samsung S4 16 characters E.g.: Cash on Delivery 14 PayTabs API Documentation V e r s i o n 2. 0
DeliveryType Delivery Type 16 characters E.g.: Fedex CustomerId Any ID Number assigned to the customer by the merchant. 16 characters E.g.: T12112312 msg_lang Optional Language of the PayPage to be created. Any other parameter or no parameter will be taken as English by default. E.g.: English / Arabic To ensure that you get multiple line items in your PayPage, please make sure to add a space before and after two continuous pipeline separator. E.g. IPhone Samsung S5 Samsung S4 4.2 Response Element Description Format result The string representation for result about the supplied data E.g.: Pay Page is created. User must go to the page to complete the payment. error_code This is present in the response, only if there is any error. 4 characters E.g.: 0002 response The response code of the processor, If the parameters are accepted. Up to 2 characters E.g.: 10 p_id PayPage ID E.g.: 123 15 PayTabs API Documentation V e r s i o n 2. 0
api_key The current API key of the merchant. This API Key will expire within 15 minutes. E.g.: W87egrw8egh payment_url The URL for the payment E.g.: http://www.paytabs.com/pay/p age/345 4.3 Response Codes Code Description 10 Pay Page is created. User must go to the page to complete the payment. 4.4 Error Codes Error Code Description 0002 API Key not valid 0404 You don't have permissions to create an Invoice. 16 PayTabs API Documentation V e r s i o n 2. 0
4.5 Example: <?php $pt->create_pay_page(array( "api_key " => 211145sds3aqmkol21314 "cc_first_name" => "John", "cc_last_name" => "Doe", "phone_number" => "123123123456", "billing_address" => "TEST BILL ADDRESS", "city" => "TEST CITY", "state" => "TEST STATE", "postal_code" => "12345", "country" => "BHR", "email" => "foo@bar.com", "amount" => "224", "discount " => "123.1" "reference_no " => "ABC-123 " "currency" => "BHD", "title" => "TEST TITLE", "ip_customer" =>"1.1.1.0", "ip_merchant" =>"1.1.1.0", "unit_price" => 12.21 21.20, "quantity" => 2 3 1, "address_shipping" => "Flat 3021 Manama Bahrain", "state_shipping" => "Manama", "city_shipping" =>"Manama", "postal_code_shipping"=>"1234", "country_shipping" => "BHR", "product_per_title" =>"MobilePhone Charger Camera", "channelofoperations"=>"physical Goods", "Product Category" =>"Electronics", "ProductName" => "MobilePhone Charger Camera", "ShippingMethod" => "Cash on Delivery", "DeliveryType" =>"FedEx", "CustomerID" =>"t12341112", "msg_lang => English, "return_url" => "Your site URL" ));?> Note: $pt represents your own class name and IS NOT any class library provided by PayTabs. It is used here just to illustrate the example. 17 PayTabs API Documentation V e r s i o n 2. 0
5 Validate API Key This method can be used at any time to validate the API Key. It is especially beneficial just before verifying a payment. If the API Key is invalid (usually after 15 minutes), a new one needs to be generated by passing the merchant credentials to the authentication API Call. PATH REQUEST METHOD PRODUCTION https://www.paytabs.com/api/api_key_valid POST LIVE 5.1 Request Element Description Format api_key API Key received from authentication API call or a valid API key E.g.: Mao8sdhasfyahosdap9sd 5.2 Response Element Description Format result Result after checking the validity of the API Key. E.g.: valid for valid API key invalid for invalid API key error_code This is present in the response, only if there is any error. E.g.: 0002 5.3 Error Codes Error Code Description 0002 API Key not valid 18 PayTabs API Documentation V e r s i o n 2. 0
6 Verify Payment This method verifies the result of the payment. It is recommended that you first verify that your API Key is still valid before verifying the payment. If the API Key has expired ( usually after 15 minutes), a new API Key has to be obtained by passing the merchant_id and password to the authentication call and then use that key to verify the payment. When you create a PayPage, you will receive p_id in the response. When the customer completed a payment and is referred back to your website, there is a payment_reference that is sent with a POST method. The payment_reference is used to verify the status of the payment whether it is a successful transaction or a failed transaction. In addition to that you can compare the payment_reference and the p_id, inorder to match the payment with its respective PayPage. PATH REQUEST METHOD PRODUCTION https://www.paytabs.com/api/verify_payment POST LIVE 6.1 Request Element Description Format api_key API Key received from authentication API call or a valid API key Up to 64 characters E.g.: Mao8sdhasfyahosdap9sd payment_reference This is a payment reference that is sent with a POST method when the customer is returned from payment page. Up to 64 characters E.g.: t2938yh202tu0 6.2 Response Element Description Format result The string representation for result, whether transaction has succeeded or failed. E.g.: Payment is completed. 19 PayTabs API Documentation V e r s i o n 2. 0
error_code This is present in the response, only if there is any error. 4 characters E.g.: 0002 response The response code of the processor, If the parameters are accepted. Up to 2 characters E.g.: 6 6.3 Response Codes Code Description 0 The payment is rejected 2 PIN rejected, payment rejected 6 Payment is completed. 3D secure is also approved (if applicable) 7 Unknown status * Response Code 6 is the response code for a successful transaction. 6.4 Error Codes Error Code Description 0002 API Key not valid. 0003 There are no transactions available. 20 PayTabs API Documentation V e r s i o n 2. 0
6.5 Example <?php function verify_payment($api_key, $payment_reference) { $values['api_key'] = $api_key; $values['payment_reference'] = $payment_reference; return json_decode(mypostdatafunction("https://www.paytabs.com/api/verify_payment", $values)); }?> 21 PayTabs API Documentation V e r s i o n 2. 0
7 Expire API Key This API call will expire the API Key after all API Calls are complete. PATH REQUEST METHOD PRODUCTION https://www.paytabs.com/api/logout POST LIVE 7.1 Request Element Description Format api_key API Key received from authentication API call or a valid API key E.g.: Mao8sdhasfyahosdap9sd 7.2 Response Element Description Format result The result of the transaction E.g.: Logged Out 7.3 Error Codes Error Code Description 0002 API Key not valid 22 PayTabs API Documentation V e r s i o n 2. 0
8 REST API Call Behavior Once the API Call for creating pay page is called and the customer is redirected to the pay page, after completing the payment, it will be redirected to return_url. While returning back to that URL, it will send a POST request to that page explained as below: Element Description Format payment_reference This is a payment reference that is sent with a POST call when the customer is returned from payment page. Up to 64 characters E.g.: t2938yh202tu0 Now you have two key values to see the status of the payment: 1. api_key : generated from the authentication call 2. payment_reference: that is sent as a POST request when customer is redirected back to the merchant website. These two parameters can provide you details about the payment if sent to verify_payment. Payment can be verified and the order status can be set accordingly in shopping carts. Security Tip: Ensure that the referrer response is originating from PayTabs.com 23 PayTabs API Documentation V e r s i o n 2. 0
9 Response & Error Codes The following table describes all the response code and error codes which may appear when working with the API. 9.1 Response Codes Code Description 0 The payment is rejected 1 The payment is prepared 2 PIN rejected, payment rejected 3 PIN accepted, payment approved 6 Payment is completed. 3D secure is also approved (if applicable) 7 Unknown status 10 Pay Page is created. User must go to the page to complete the payment. 9.2 Error Codes Code Description 0001 Merchant ID and password does not match. 0002 API Key not valid. 0003 Transaction ID not found. 0004 Unknown transaction error occurred. 0005 The currency code is not available for this merchant. 0404 You don t have permissions to create an Invoice. 24 PayTabs API Documentation V e r s i o n 2. 0
10 Test Credit Card Numbers To test your payment process, you can typically use any valid credit card number or you can use the ones listed below. Please do not use test cards in a live environment. This will cause your transactions to be rejected. Card Number Description CVV Expiry Date 4000 0000 0000 0002 With authentication window 1234 01/2016 4000 0000 0000 0127 Card enrollment option during purchase process 1234 01/2016 5200 0000 0000 0007 With authentication window 1234 01/2016 5200 0000 0000 0114 5200 0000 0000 0122 Without authentication window Card enrollment option during purchase process 1234 01/2016 1234 01/2016 3742 4545 5400 001 NON-KSA AMEX CARD 1234 12/2016 3766 5500 2678 115 KSA AMEX CARD DETAILS 7455 12/2016 25 PayTabs API Documentation V e r s i o n 2. 0
11 Example <?php @session_start(); // Defining Variables for the API CALLS define("testing", "https://www.paytabs.com/api/index"); define("authentication","https://www.paytabs.com/api/authentication"); define("paypage_url", "https://www.paytabs.com/api/create_pay_page"); // Your own class class paytabs{ private $merchant_id; private $merchant_password; private $api_key; // Function to Initiate Class Variables function paytabs($merchant_id, $merchant_password) { $this->merchant_id = $merchant_id; $this->merchant_password = $merchant_password; $this->api_key = ""; } // Function to Authenticate Merchant ID & Password and obtain API Key function my_function_to_authentication() { $obj = json_decode(my_function_to_post_data(authentication, array("merchant_id"=> $this->merchant_id, "merchant_password"=> $this->merchant_password))); // On successful authentication, an API Key is returned. if($obj->access == "granted") { $this->api_key = $obj->api_key; } else { $this->api_key = ""; } return $this->api_key; } 26 PayTabs API Documentation V e r s i o n 2. 0
// Function to Create PayPage function my_function_to_create_paypage ($values) { $values['api_key'] = $this->api_key; $values['cc_first_name'] = "John"; $values['cc_last_name'] = "Doe"; $values['phone_number'] = "39882135"; $values['billing_address'] = "Flat 3021 Manama Bahrain"; $values['state'] = "Manama"; $values['city'] = "Manama"; $values['postal_code'] = "12345"; $values['country'] = "BHR"; $values['email'] = "customer@domain.com"; $values['amount'] = "234.699"; $values['discount'] = "34.699"; $values['reference_no'] = "ABC-5542"; $values['currency'] = "BHD"; $values['title'] = "Order No 1223"; $values['ip_customer'] = "1.1.1.0"; $values['ip_merchant'] = "127.168.1.0"; $values['return_url'] = "http://www.mywebsite.com/paymentcomplete"; $values['address_shipping'] = "Flat 3021 Manama Bahrain"; $values['state_shipping'] = "Manama"; $values['city_shipping'] = "Manama"; $values['postal_code_shipping'] = "12345"; $values['country_shipping'] = "BHR"; $values['quantity'] = "1 2 1 "; $values['unit_price'] = "21.199 22.100 12.300"; $values['products_per_title']= "MobilePhone Charger Camera"; $values['channelofoperations'] = "Physical Goods"; $values['product Category'] = "Electronics"; $values['productname'] = "MobilePhone Charger Camera"; 27 PayTabs API Documentation V e r s i o n 2. 0
$values['shippingmethod'] = "Cash On Delivery"; $values['deliverytype'] = "FedEx"; $values['customerid'] = "t12341112"; $values['msg_lang'] = "English"; return json_decode(my_function_to_post_data(paypage_url, $values)); } // Create your own function to post the data to PayTabs. function my_function_to_post_data($url, $fields) { // Send Data to PayTabs // Here you need to write a function to send the data prepared in the // previous function to PayTabs via curl or any other method. } }?> 28 PayTabs API Documentation V e r s i o n 2. 0