eCheckoutLK IPG JS

eCheckoutLK IPG JS helps to integrate the eCheckoutLK Payment Gateway to your website.

The eCheckoutLK Payment Gateway Integration

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

• Merchant Key:
• Merchant Token:

You can simply use an HTML Form to submit the below params to eCheckoutLK Payment Gateway.When your customer clicks on the payment/checkout button, It will be redirected to the eCheckoutLK Payment Gateway. The Customer can confirm the payment by clicking on the 'continue' button. Then your customer will be securely redirected to the 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 eCheckoutLK 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 eCheckoutLK IPG JS package in your project.

1.1. Run the following command inside your project.

npm i echeckout-ipg-js

1.2. Import the eCheckoutLK IPG JS package.

import { echeckoutPayment } from "echeckout-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 - eCheckoutLK Merchant ID [Given by eCheckout]
• 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 eCheckoutLK which then encrypted with merchant token (a unique Secret value for the Merchant which was shared by eCheckout) 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 eCheckoutLK SDK.

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

echeckoutPayment(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

eCheckoutLK 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",
  "echeckoutOrderId": "oid-XXXXXXXX-XXX-XXXX-XXXX-XXXX",
  "echeckoutTransactionId": "XXXXXXXX-XXX-XXXX-XXXX-XXXXXXXXX",
  "echeckoutAmount": "1000.60",
  "echeckoutCurrency": "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

• echeckoutOrderId - Unique Order Id generated by eCheckout
• echeckoutTransactionId - Unique Transaction Reference Id generated by eCheckoutLK for the processed payment
• echeckoutAmount- Total amount of the Payment
• echeckoutCurrency - 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
}

eCheckoutLK Payment Gateway Integration