WooCommerce v3.0

Installation

This document illustrates how our gateway can be integrated with WooCommerce plugin in simple and easy steps. Please follow the steps in order to integrate the Paytala plug-in with your WordPress/WooCommerce website.

  1. Download the plugin from WooCommerce.
  2. Add the files into the “wp-content/plugins” directory within your word press installation.

Activation

  1. To activate the plugin, log into the admin panel and go to the Plugin section. You will then see the Credit Card Payment Plugin. Click on “Activate” to install the plugin

Configuration

After you activate the plugin, go to WooCommerce section >> Settings >> Checkout and select Paytala

You have to Login and goto “Merchants Websites” to get your Merchant ID and secret-key

  1. You can find the secret key on your Merchant’s Dashboard >> Secret Key.
  2. For Website: Enter the website URL you provided in your Paytala merchant account.

Older versions

  • Version 2.6 – Credit card

OpenCart 3

 

Installation

This document illustrates how our gateway can be integrated with Open Cart 3 plugin in simple and easy steps. Please follow the steps in order to integrate the paytala plug-in with your Open Cart 3 website.

Download the plugin from Downlaod.

Manual Install via FTP:

Upload the content of ‘upload’ folder included in the extension zip to your OpenCart site root via FTP application.

Configure paytala Extension:

  1. Login to OpenCart Admin panel.
  2. Go to Extensions
  3. Select Payments from dropdown and locate for paytala extension.
  4. Click the Install button on right of the extension.
  5. Once installed, click the Edit or Configure button of the extension. Enter Merchant Email, Merchant ID and Secret Key.
  6. Success Order Status may be ‘Processing’ as that will help you to understand for which orders payments received.
  7. Cancel / Fail Order status should be ‘Canceled’.
  8. Status must Enabled.
  9. Sort Order may be used if you are using multiple checkout payment options and to control order of occurrence within those.
  10. Save the Configuration and go to Shop Front and try checkout.
  11. If Configuration is ok then you should see paytala payment window during payment.

Older versions

Magento 2.x

This is a Express Checkout module. In order to integrate with PayTabs Payment Plugin for your eCommerce solution, you will need the credentials of your paytala Merchant Account. If you do not have a merchant account, you can sign up for one here.

Installation

Download the plugin from Github.

Extract the zip file and upload ‘paytala’ folder to Magento <root>/app/code.

  1. Run the magento commands –

php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy

Copy

( or compile, if you need to check dependencies. Refer Magento 2.x documentation for various options)

  1. Follow the configuration section to configure the module in Magento Admin panel.

Configuration

You have to Login to get your secret-key and merchant-id

  1. Login and Navigate to Store >> Configuration >> Sales >> Payment Methods. Expand the tab named ‘Paytabs Express Checkout’.
  2. Fill up the configuration details which can be found in your merchant dashboard.
  3. After your have setup information in step 2, click on Save Config and you can have your customers make payment via the payment method.

Older versions

  • Create paypage API

    Overview

    Creates a paypage based on the prefilled parameters passed in the request. It returns a payment link which requires the customers to

    Download Sample Code

    enter only their card details to make the payment.image

    POST https://pay.paytala.com/api/apiv2/create_pay_page

    Request

    You are required to Login to obtain merchant_email and secret_key

    Element Description
    merchant_email

    Merchant email id used to login into paytala Merchant Dashboard.
    secret_key 
     
    Secret key generated by merchant dashboard. Merchant Dashboard > Navigation Menu > Secret Key
    site_url 
     
    The URL of your site from which you will configure the API. Example: http://www.yourwebsite.com/
    return_url 

    After payment completion, the user will be redirected to this URL to show the response. Example: http://yourwebsite.com/payment_completed.php
    title 
     
    Description or title of the transaction done by the customer. Example: Billing for Order #1234, or Bill To Mr. John Doe, etc
    cc_first_name 

    First Name of the Customer
    cc_last_name 
     
    Last Name of the Customer
    cc_phone_number 
     
    Country code for Phone Number of the Customer
    Example: UAE country code is 00971
    USA country code is 001
    phone_number 
     
    Phone Number of the Customer. Minimum 6 numbers and Maximum 15
    email 
     
    Email of the customer
    products_per_title 
     
    Product title of the product. If multiple products then add || separator. To ensure that you get multiple line items in your PayPage, please make sure to add a space before and after two continuous pipeline separators.
    unit_price 
     
    Unit price of the product. If multiple products then add || separator.
    quantity 
     
    Quantity of products. If multiple products then add || separator. To ensure that you get multiple line items in your PayPage, please make sure to add a space before and after two continuous pipeline separators.
    other_charges 
     
    Additional charges. e.g.: shipping charges, taxes, VATs, etc.
    amount 
     
    Amount of the products and other charges, it should be equal to: amount = (sum of all products’ (unit_price * quantity)) + other_charges. This field will be displayed in the invoice as the sub total field
    discount 
     
    Discount of the transaction: The Total amount of the invoice will be= amount - discount
    currency 
     
    Currency of the amount stated. 3 character ISO currency code.
    Example: USD for US dollars 
    AED for Emirati Dirham 
    SAR for Saudi Riyal
    reference_no 
     
    Invoice reference number
    ip_customer 
     
    The client IP with which the order is placed
    ip_merchant 
     
    Server IP where the order is coming from
    billing_address 

    Complete Address of the customer. Multiple address lines will be merged into one single line. Maximum length is 40
    state 
     
    Billing State (part of the address) entered by the customer. For USA and Canada please use the correct state and province 2-character codes. https://www.ups.com/worldshiphelp/WS16/ENU/AppHelp/Codes/State_Province_Codes.htm
    city 
     
    Name of the billing city selected by customer. Maximum length is 50
    postal_code 
     
    Billing Postal code provided by the customer. When the country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits]Example 12345-6789When the country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space][numeric][alpha][numeric] Example A1B 2C3
    country 
     
    Country of the customer. 3-Character ISO country code. 
    Examples: ARE for United Arab Emirates
    SAU for Kingdom of Saudi Arabia
    USA for United States of America
    shipping_first_name
     
    First Name of the Customer in shipping address
    shipping_last_name 

    Last Name of the Customer in shipping address
    address_shipping 
     
    Shipping address of the customer
    city_shipping 
     
    Shipping City of the customer. Maximum length is 50
    state_shipping 
     
    Shipping State of the customer. For USA and Canada please use the correct state and province 2-character codes. https://www.ups.com/worldshiphelp/WS16/ENU/AppHelp/Codes/State_Province_Codes.htm
    postal_code_shipping 

    Shipping postal code of the customer. When the country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example 12345-6789 When the country is Canada, the 6-digit postal code must follow this format:[alpha][numeric][alpha][space][numeric][alpha][numeric]Example A1B 2C3
    country_shipping 
     
    Shipping country of the customer. 3-Character ISO country code. 
    Examples: ARE for United Arab Emirates
    SAU for Kingdom of Saudi Arabia
    USA for United States of America
    msg_lang 
     
    Language of the PayPage to be created. Invalid or blank entries will default to English. Paypage supports only two Languages: English and Arabic
    cms_with_version 
     
    CMS / Language that you are using with its version. This will help us to troubleshoot issues, if any

    Payment Type

    If your merchant account supports multiple payment options on the same paypage for example (For Saudi Arabia Merchants) A paypage for a SAR payment can have three payment options on the same payment page: Credit Card, MADA and SADAD. If you wish to create a paypage with only one option you need to pass an additional field in the request

    Element Description
    payment_type You can pass any of the below values:
    Credit card: Will create a payment page with credit card option only even if there are other payment types enabled for your account for a certain currency. 
    SADAD: Will create a payment page with SADAD option only even if there are other payment types enabled for your account for SAR currency. 
    MADA: Will create a payment page with MADA option only even if there are other payment types enabled for your account for SAR currency. 
    KNPAY: Will create a payment page with KNPAY option only even if there are other payment types enabled for your account for KWD currency. 
    OMANNET: Will create a payment page with OMAN NET option only even if there are other payment types enabled for your account for OMR

    Response

    For Successful PayPage Creation:
    If all the parameters are passed correctly to the API, you should receive the following json response from the API call. You should parse it and then redirect your customer to the PayPage URL that you received in the response.
    {
    "result": "The Pay Page is created.",
    "response_code": "4012",
    "payment_url": "https://pay.paytala.com/api/iejy3Tj1qgimGrKOCW6osjqpB7gny2yZqdeGDwZzYQC1D7Q/EdiZfntl_ifDikE3Iu74ojqwPECdvOnFjcz7mdFDDsNHcV8/D9pWPCdpchbX98JebfY-ER-zd4JzpntTQkNkiv7KXz8WLgY/ziCmQrZ1XboE0Px8-cwzTlNeX_SPBXq6Ae4PqUfe3xS0f1ESuUzOPF-oUAjM1d48on7Fh6W-53KL8nrygR_OUwh8JA 〈https://pay.paytala.com/api/iejy3Tj1qgimGrKOCW6osjqpB7gny2yZqdeGDwZzYQC1D7Q/EdiZfntl_ifDikE3Iu74ojqwPECdvOnFjcz7mdFDDsNHcV8/D9pWPCdpchbX98JebfY-ER-zd4JzpntTQkNkiv7KXz8WLgY/ziCmQrZ1XboE0Px8-cwzTlNeX_SPBXq6Ae4PqUfe3xS0f1ESuUzOPF-oUAjM1d48on7Fh6W-53KL8nrygR_OUwh8JA〉 ",
    "p_id": 2379271
    }

    Copy

    For Failed PayPage Creation:
    In case there is an issue in the parameters you are passing to the API, you will receive a similar response, which describes the reason for not creating the paypage in the result variable.
    {
    "result":"Your SITE URL is not matching with your profile URL",
    "response_code":"4008",
    "payment_url":""
    }

    Copy

    Sample code
    <?php
    $pt->create_pay_page(
    array(
    "merchant_email" => "merchantaccount@gmail.com",
    "secret_key" => "211145sds3aqmkol21314",
    "site_url" => "https://www.yourwebsite.com",
    "return_url" => "https://www.yourwebsite.com/return",
    "title" => "JohnDoe And Co.",
    "cc_first_name" => "John",
    "cc_last_name" => "Doe",
    "cc_phone_number" => "00973",
    "phone_number" => "123123123456",
    "email" => "johndoe@example.com",
    "products_per_title" => "MobilePhone || Charger || Camera",
    "unit_price" => "12.123 || 21.345 || 35.678 ",
    "quantity" => "2 || 3 || 1",
    "other_charges" => "12.123",
    "amount" => "136.082",
    "discount" => "10.123",
    "currency" => "BHD",
    "reference_no" => "ABC-123",
    "ip_customer" =>"1.1.1.0",
    "ip_merchant" =>"1.1.1.0",
    "billing_address" => "Flat 3021 Manama Bahrain",
    "city" => "Manama",
    "state" => "Manama",
    "postal_code" => "12345",
    "country" => "BHR",
    "shipping_first_name" => "John",
    "shipping_last_name" => "Doe"
    "address_shipping" => "Flat 3021 Manama Bahrain",
    "state_shipping" => "Manama",
    "city_shipping" => "Manama",
    "postal_code_shipping" => "1234",
    "country_shipping" => "BHR",
    "msg_lang" => "English",
    "cms_with_version" => "WordPress4.0-WooCommerce2.3.9"
    ));
    ?>

    Copy

    Note: $pt represents your own class name and IS NOT any class library provided by paytala. It is used here just to illustrate the example

    REST API Call Behavior (After Payment Completion)

    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
    payment_reference This is a payment reference that is sent with a POST call when the customer is returned from payment page which is same as the p_id returned in the API response when the paypage is created

    Now you have three key values to see the status of the payment:

    1. merchant_email: Merchant email from which you are trying to login into paytabs system
    2. secret_key : SECRET Key generated by merchant dashboard
    3. payment_reference: the p_id that is sent in the api response along with the paypage url or the value 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.

    Verify Payment

    Overview

    Returns the transaction details.

    POST https://pay.paytala.com/api/apiv2/verify_payment

    Request

    You have to Login to get your merchant_id and secret_key

    Element Description
    merchant_email 

    Merchant email from paytala Merchant Dashboard.
    secret_key 

    Secret key can be found at the merchant dashboard
    payment_reference

    This is the p_id that is returned in the response of create PayPage when the page is created successfully.

    Response
    {
    "result": "The payment is completed successfully!",
    "response_code": "100",
    "pt_invoice_id": "2124779",
    "amount": 11.45,
    "currency": "OMR",
    "reference_no": "12",
    "transaction_id": "1720833"
    }

    Copy

    Response Codes

    Response Code Description
    4001 Variable not found
    4002 Invalid Credentials
    0404 You don’t have permissions
    400 There are no transactions available.
    100 Payment is completed.
    481 - 482 This transaction is under review and will be reversed based on your card issuing bank's policy, if its not approved within 24 hours