PAYable IPG JS

PAYable IPG JS helps to integrate the payment gateway of your website.

The Payable Payment Gateway Integration

First, You need to get the Merchant Key and Merchant Token to integrate with the IPG SDK from Payable.

• Merchant Key:
• Merchant Token:

You can simply use an HTML Form to submit the below params to Payable Payment Gateway.When your customer clicks on the payment/checkout button, It will be redirected to the Payable Payment Gateway. The Customer can confirm the payment by clicking on the 'continue' button. Then your customer will be securely redirected to the commercial bank Payment Gateway and the customer can then enter the credentials (Card No / Cardholder name / CVV ) and process the payment there. Once the payment is made, The payable payment gateway will show the payment status to your customer and send the receipt to your customer's email.

Version V4 - v4.1.1

Implementation

1. Install Payable IPG JS package in your project.

1.1. Run the following command inside your project.

npm i payable-ipg-js-qa

1.2. Import the Payable IPG JS package.

import { payablePayment } from 'payable-ipg-js-qa';

2. Create your payment request with basic required fields.

2.1. Required Form Parameters:

• notifyUrl - URL to callback the status of the payment (Needs to be a URL accessible on a public IP/domain)
• returnUrl - URL to redirect users when success
• logoUrl - Logo url to show the logo in SDK
• merchantKey - Payable Merchant ID [Given by PAYable]
• currencyCode - Currency Code (LKR/EUR/GBP/USD)
• checkValue - Generated hash value to ensure extra security
• orderDescription - Small Description for the Order
• amount - Total Payment Amount
• invoiceId - Invoice ID generated by the merchant
• paymentType - Payment Type (1 means ONE_TIME_PAYMENT, 2 means RECURRING_PAYMENT)
• customerFirstName- Customer’s First Name
• customerLastName - Customer’s Last Name
• customerMobilePhone- Customer’s Mobile No
• customerEmail - Customer’s Email
• billingAddressStreet - Billing Address Line1
• billingAddressCity- Billing City
• billingAddressCountry - Billing Country

2.2. Payment type Parameters: Following parameters are required if the payment type is 2

• startDate - Payment Start Date
• endDate - Payment End Date (It can be any date or FOREVER)
• recurringAmount - Recurring payment Amount
• interval - Payment Interval (It can be MONTHLY,YEARLY)
• isRetry - Is Retry
• retryAttempts - Retry Attempts
• doFirstPayment - Do First Payment

2.3. Optional Form Parameters:

• custom1 - Merchant specific data, a Custom 1
• custom2 - Merchant specific data, a Custom 2
• customerPhone - Customer’s Phone No
• billingAddressStreet2 - Billing Address Line2
• billingCompanyName - Billing Company
• billingAddressPostcodeZip - Billing Postal Code
• billingAddressStateProvince - Billing Province
• shippingContactFirstName - Shipping Contact First Name
• shippingContactLastName - Shipping Contact Last Name
• shippingContactMobilePhone - Shipping Contact Mobile No
• shippingContactPhone - Shipping Contact Phone No
• shippingContactEmail - Shipping Contact Email
• shippingCompanyName - Shipping Contact Company
• shippingAddressStreet - Shipping Address Line1
• shippingAddressStreet2 - Shipping Address Line2
• shippingAddressCity - Shipping City
• shippingAddressStateProvince - Shipping Province
• shippingAddressCountry - Shipping Country (LKA)
• shippingAddressPostcodeZip - Shipping Postal Code

In Request, checkValue is a combination of merchant key, invoice id, amount, currency parameter set in a predefined sequence given by PAYable which then encrypted with merchant token (a unique Secret value for the Merchant which was shared by PAYable) using SHA-512.

Format:

UPPERCASE(SHA512[<merchantKey>|<invoiceId>|<amount>|<currencyCode>|UPPERCASE(SHA512[<merchantToken>])])

2.3. Sample form :

const payment = {
      logoUrl: "https://domain/images/logo_name",
      returnUrl: "https://domain/your_return_url",
      checkValue: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      orderDescription: "Payment for furni",
      invoiceId: "INVSXz7qcw3Br",
      merchantKey: "XXXXXXXXXXXXXXXXX",
      customerFirstName: "customer first name",
      customerLastName: "customer last name",
      customerMobilePhone: "077XXXXXXX",
      customerEmail: "[email protected]",
      billingAddressStreet: "Main street",
      billingAddressCity: "Vavuniya",
      billingAddressCountry: "LKA",
      amount: "235.00",
      currencyCode: "LKR",
      paymentType: "1"
  };

3. Communicate with PAYable SDK.

3.1. Submit your form json data into payablePayment(). payment is the payment object and testMode is boolean. If the test mode is true, it will conected to Dev env.

payablePayment(payment, testMode);

3.2. Payment related Error details.

Error will be field validation (code : 3009) and other common errors.

This is the sample validation error json

   {
        "status": 3009,
        "success": false,
        "error": {
            "startDate": [
                "Start date should be today date."
            ]
        }
    }

Other common error(status can be 400/500/any other)

   {
        "status": 400,
        "success": false,
        "error": "Something went wrong. Please contact your merchant."
    }

Listening to Payment Notification Data

Payable Payment Gateway will send back to your website notifies the payment status to the notifyUrl. You need to get the request and send the response.

• It cannot test the payment notification by print/echo methods since notifyUrl never loads to the browser as it's a server callback. You can only test it by updating your database upon fetching the notification.
• It cannot test the payment notification on localhost. You need to submit a publicly accessible IP or domain based URL as your notifyUrl is to directly notify your server.

Server callback Json

{
    "merchantKey": "SXXXXXXXX",
    "payableOrderId": "oid-XXXXXXXX-XXX-XXXX-XXXX-XXXX",
    "payableTransactionId": "XXXXXXXX-XXX-XXXX-XXXX-XXXXXXXXX",
    "payableAmount": "1000.60",
    "payableCurrency": "LKR",
    "invoiceNo": "INVvw5EA0d1pH",
    "statusCode": 1,
    "statusMessage": "SUCCESS",
    "paymentType": 1,
    "paymentMethod": 1,
    "paymentScheme": "MASTERCARD",
    "custom1": "test 1",
    "custom2": "test 2",
    "cardHolderName": "Shakthi",
    "cardNumber": "512345xxxxxx0008",
    "checkValue": "256XXXXXXXXXXXXXX"
}

Description

• payableOrderId - Unique Order Id generated by PAYable
• payableTransactionId - Unique Transaction Reference Id generated by PAYable for the processed payment
• payableAmount- Total amount of the Payment
• payableCurrency - Currency Code of the Payment (LKR Only)
• invoiceNo - Unique Id sent by Merchant to the Checkout page
• statusMessage - Message received from payment gateway which the customer tried to pay(SUCCESS/FAILURE)
• paymentType - Payment type selected during the Checkout
  1. CARD (SUPPORTED)
  2. BANKING (Not implemented yet)
  3. WALLET (Not implemented yet)
• paymentMethod - Payment method selected during the Checkout
  1. VISA / MASTERCARD / CUP(Visa and Mastercard are SUPPORTED / CUP Not implemented Yet)
  2. AMEX / DINERS CLUB / DISCOVER
  3. SAMPATH VISHWA (Not implemented yet)
• paymentScheme - Payment scheme selected by the customer (VISA / MASTERCARD)

If the customer made the payment by VISA or MASTER credit/debit card, following cardHolderName and cardNumber parameters will also be available.

• cardHolderName -Name on the Card
• cardNumber - Masked card number (Ex: ************0008)

Send response to callback

{
    "Status":200
}

PAYable Payment Gateway Integration