Payable-ipg-js NPM

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.2

Implementation

1. Install Payable IPG JS package in your project.

1.1. Run the following command inside your project.

npm i payable-ipg-js

1.2. Import the Payable IPG JS package.

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

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: "testmail@gmail.com",
      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 Sandbox 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)