iPay Web Payment Integration

Document

Ver. 1.0.0

Prepared By:
iPay (Pvt) Limited
No. 984 | Kotte Road | Ethul Kotte | Sri Lanka
Web : www.ipay.lk
Table of Contents

iPay Web Payments Integration .................................................................................................................... 2

How iPay Web Payments works ................................................................................................................... 2

iPay Web Merchant Integration JavaScript Library...................................................................................... 4

Checkout Script Functions ............................................................................................................................ 5

Call-back API Parameters ............................................................................................................................. 5

Verifying Payment Status ............................................................................................................................. 6

iPay Web Payment Button ............................................................................................................................ 7

iPay Web Payments Integration

iPay Web Payments gives your purchasers a rearranged checkout encounter that keeps them
neighborhood to your site or mobile application all through the payment authorization process and
gives them a chance to utilize bank account to pay without sharing or entering any sensitive data
on your site.

How iPay Web Payments works

1. Go to the iPay website using following URL.

Sandbox: https://sandbox.ipay.lk
Production: https://ipay.lk

Register as a merchant. Next log in to the merchant portal by using the username and password.

2. Go to the ‘Merchant Settings’ on the side bar and click on ‘Development Settings’.
Then the page will display a check box which enables the development options. Then the
merchant should enable development by clicking on the checkbox.
3. After enabling development option ‘Developer Portal’ will automatically display on the side
bar. Then go to the ‘Payment Integration’ and merchant should generate his web token by
giving required details.

4. Then Merchant should give value for the ‘Secret’ option. This secret code is used to make
checksum.

5. Merchant should give a Call back API URL. This is use to notify the payment status.

6. Web Token will be automatically displayed when merchant click on Generate Token button.
It is specified for the merchant and when using the JavaScript file which is given for the
merchant from iPay, merchant should use this ‘web token’ in JavaScript file.
iPay Web Merchant Integration JavaScript Library
Merchants have to import iPay JavaScript library in to merchant’s webpage. Merchants should not
download the iPay JavaScript library and use it locally. Merchant should always use the Library
using the CDN given below.

NOTE: If a merchant hasn’t added the JQuery CDN to merchant’s web page, he/she has to add
following script as well to his/her webpage.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>

SANDBOX
<script src="https://sandbox.ipay.lk/resources/js/ipay-web-payments-1.0.0.min.js"></script>

PRODUCTION
script src="https://ipay.lk/resources/js/ipay-web-payments-1.0.0.min.js"></script>

After those steps implement iPay’s JavaScript checkout code snippet in to your web page. (An
example is given below).

ipaywebpayment({
env: 'sandbox', // sandbox | production
token : {
sandbox : 'eyJhbGciOiJIUzUxMiJ9.eyJiYW5rQWNjb3VudCI6ImFjYy5l2RlIjoiZWNoIiw',

production : ''
},
drawPayButton : false, // optional

// payment() is called when the button is clicked

payment: function() {
return payInfo({
totalAmount : 1800.00,
currency : 'LKR',
additionalAttributes : {}
// merchant additional attributes if any (optional)
});
},
//onConfirm() is called when the buyer confirms the payment or scan the QR code
onConfirm: function(data) {
//merchant should save the transaction reference against the order
},
 //onAuthorize() is called when the buyer make the payment by iPay mobile
application
onAuthorize: function(data) {
// merchant should validate the transaction status with their backend
}
}, "#btnPay"); // html element (button, href etc..)

Checkout Script Functions

Function called by the script when a buyer clicks on the iPay button or
Payment()
the particular button given by the website for checkout.
Function called by the script when the buyer confirms the payment or
onConfirm() scan the QR code by iPay APP. Merchant should save the transaction
reference against the order.

Function called by the script when the customer make the payment by
onAuthorize()
iPay APP.

Once the payment is authorized by customer, iPay will trigger onAuthorize() function and notify the
payment status to your call-back API same time. Payment notification will contain the following
data as POST parameters, so you need to make sure the call-back API URL you set is accepting
these parameters on a POST request & update your database accordingly.

Call-back API Parameters

Parameter Name Data Type Description

transactionReference String IPay web payment reference number for

particular transaction
transactionTImeInMillis String Transaction initiated time in milliseconds
transactionAmount String Transaction amount passed to iPay from web
merchant to proceed the transaction.
creditedAmount String Amount credited to web merchant account
after deducting commissions
 transactionStatus String Status of the transaction (A, P, D)
transactionMessage String Message for the transaction
additionalAttributes Json Merchant additional attributes provided at the
initiation of the web payment
checksum String Checksum generated using payload data

Transaction status codes

A - Accepted (Transaction process is successfully completed)
P - Pending (Money successfully deducted from the customer bank account, but unable to transfer to
merchant’s account. The amount will be transferred at the EOD)
D - Decline (Transaction failed)

Verifying Payment Status

It is important to verify payment notification before taking any action on the payment response. You can
do the verification using the checksum parameter generated and sent by iPay.

The checksum is generated using the below combination of parameters. Checksum is generated
using HMAC SHA256 algorithm.

message = transactionReference + transactionTimeInMillis + transactionAmount +

creditedAmount + transactionStatus + transactionMessage + secret

checksum = H (key1 || H (key2 || message))

PS: refer the below links for further clarification

https://en.wikipedia.org/wiki/HMAC

https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-
different-languages/

Once you receive the payment notification from iPay, you can locally generate this checksum
using above mentioned parameters and the secret you have locally. Your locally generated
checksum should equals to the checksum sent by iPay if the payment notification is valid.
And also once we invoke the call-back API, you should return HTTP response code 200 (OK) if
your whole operation is succeeding from your side. Any other HTTP response code will be taken
as failure responses.

iPay Web Payment Button

iPay Web Payments comes with a default iPay button which is used to do start the payment process.
Merchants can either use the default button (which is a div tag) given or any custom button (any
relevant tag) or element according to the wish of the merchant.