IME PAY MOBILE INTEGRATION GUIDE
Version 2.0.1
By
IME Digital Solution Ltd.
IME Complex, Panipokhari
Kathmandu, Nepal
1
Documentation Control
Revision History
Version Date Remarks
1.0.0 08/15/2017 Initial Draft
1.1.0 11/21/2017 Added page to enter mobile number and
second factor for Authentication via OTP
1.2.0 09/03/2018 Added iOS process and GitHub links
1.3.0 11/06/2019 Added SSL & modified Android GitHub links
2.0.0 24/08/2020 Delivery Url added for Merchant
2.0.1 15/09/2020 SDK Methods improved
links
2
Contents
Documentation Control........................................................................................................................... 2
Revision History ................................................................................................................................. 2
Introduction............................................................................................................................................. 4
Background ........................................................................................................................................ 4
IME pay Checkout Process Overview: .................................................................................................. 5
Introduction........................................................................................................................................ 5
Prerequisites ...................................................................................................................................... 5
Steps....................................................................................................................................................... 6
Step 1 ................................................................................................................................................. 6
Step 2 .................................................................................................................................................. 7
Step 3 .................................................................................................................................................. 8
Step 4 .................................................................................................................................................. 8
Step 5 .................................................................................................................................................. 9
Step 6 .................................................................................................................................................. 10
Step 7 .................................................................................................................................................. 10
Contacts .................................................................................................................................................. 12
BUSINESS.......................................................................................................................................... 12
TECHNICAL....................................................................................................................................... 12
3
Introduction
Background
IME Digital Solution Ltd. is a subsidiary of IME Group established under the payment and
settlement bylaws 2072, with an aim to provide digital financial services to customers in
partnerships with banks/FIs as well as telecom operators and aggregators, deployed through self-
service as well as agent-based delivery channel.
IME Digital intends to introduce mobile money service, with name IME pay, under its digital
financial services initiative and offer a wide range of payment services to remittance customers
existent with money transfer associate company IME Ltd. and also cater to the vast majority of
unbanked and under-banked customers of Nepal. IME pay can be accessed via mobile and can be
serviced through any of the 5000 plus strong agent network of IME and beyond.
4
IME pay Checkout Process Overview:
Introduction
This document describes the process for successfully integrating IME pay into your transaction
process, explaining how to facilitate communication between your mobile app and the IME pay.
Payment via IME Pay SDK completes in merely 3 steps:
1. Customer selects IME Pay as the payment method in merchant’s app.
2. Customer Enters wallet number and PIN.
3. Customer completes the transaction.
Note: this document helps to integrate IME Pay SDK to your native mobile app (iOS & Android)
Prerequisites
Merchants should create below api URL in order to integrate their mobile app with IME Pay
1. Recording Service:
Merchants accepting payments directly from mobile app are special merchant and thus,
must create a transaction recording api and provide the URL as parameter while calling
the method performpayment in step 2. The API request response format is given in Step
4.
2. Delivery Service:
Merchant needs to create a delivery service webhook api, which accepts 5 parameters
that will inform the merchant system whether the payment is successful in IME pay or
not. And the details should be updated on the table. The API request response format is
given in Step 5.
5
Steps
Note: For iOS setup please visit https://github.com/imepay/imepaySDK_iOS
Step 1
1. Add IME Pay SDK gradle dependency to your project.
2. In your activity create an instance for IMEPayment.
IMEPayment imePayment = new IMEPayment(activity.this, ENVIRONMENT.LIVE);
Note: Use ENVIRONMENT.TEST for test purposes.
Link to the SDK file:
Android:
implementation 'com.swifttechnology.imepaysdk:payment-service:4.0.1'
https://github.com/imepay/imepaySDK_android
IOS:
https://github.com/imepay/imepaySDK_iOS
6
Step 2
Using the instance of IME Pay, call the method performpaymentV1().
IMEPayment imePayment = new IMEPayment(activity.this, ENVIRONMENT.LIVE);
imePayment.performPaymentV1(“MERCHANT_CODE”,
“MERCHANT_NAME",
“RECORDING_SERVICE_URL”,
“DELIVERY_SERVICE_URL”,
"AMOUNT",
"REFERENCE_ID",
"MODULE",
"USERNAME",
"PASSWORD",
new IMEPaymentCallback() {
@Override
public void onSuccess(int responseCode, String transactionId, String msisdn,
String amount, String refId) {
// Response Code 100 : Transaction successful.
// Response Code 101 : Transaction failed.
// transactionId : Unique ID generated from IME pay system
// amount: Amount paid by customer
// refId : Reference Value
}
//Override
//public void onTransactionCancelled(String refID){
// Your code to handle , if transaction cancelled by user
//}
});
- onSuccess :
Whenever the final payment transaction is initiated by SDK after all the authentication process,
this method gets invoked by the SDK either the transaction get success or failed with the
parameters described above in Step 2.
- onTransactionCancelled :
Before the final payment transaction, if the user cancel the payment process by clicking the back
button or anything else, this method gets invoked by the SDK with the parameter described above
in Step 2.
Note:
* [Username, Password, Module] will be provided by IME pay at the time of registration.
** TokenId should be valid for only one time. For every new transaction new TokenId should be
used.
7
Step 3
User enters IME Pay wallet number (mobile number) on IME Pay SDK. SDK, then requests
token id to IME Pay system.
Step 4
IME pay responds the SDK with token id. SDK then requests the merchant’s SDK Api URL
with below parameters:
The API should accept the request with four parameters as below
{
"MerchantCode":"M0001",
"ReferenceId ":"Ref-9901",
"TokenId ":"201612151220041022",
"Amount":"10.98"
}
API should respond to the SDK as below:
{
"ResponseCode":"0",
"ReferenceId":"Ref-9901",
"ResponseDescription": "Payment Request Recorded"
}
The merchant’s payment recording URL should store the values sent in SDK request. For this,
merchant should maintain a database table to store request received from SDK. The table must
contain the columns in the specified format. The records of each transaction are stored on this
table, which allows to recheck any failed transactions. This allows merchants to reconfirm and
complete the failed transactions, which may have occurred due to various reasons.
Column Name Data Type Description
MerchantCode VARCHAR(10) Will be provided by IME Pay
TranAmount MONEY Amount involved in the transaction
RefId VARCHAR(20) Unique id generated by merchant’s system
TokenId VARCHAR(20 Will be provided to SDK by IME Pay at the end of Step 2
TransactionId VARCHAR(20) IME Pay generated unique TransactionId
Msisdn VARCHAR(20) IME Pay Wallet ID
TranStatus TINYINT Txn Status at IME Pay End
StatusMessage VARCHAR(50) Txn Status Message
RequestDate DATETIME Txn Requested DateTime (Time of Recording)
ResponseDate DATETIME Txn Response received DateTime (Time of Txn Response)
8
Step 5
Merchant need to develop a delivery Url where IME Pay will post a transaction response.
Delivery Url should not be restricted by any authorization:
Request JSON parameters will be as below:
{
"MerchantCode":"M0001",
"RefId":"Ref-9901",
"TokenId":"201612151220041022",
"ResponseCode":"0",
"Msisdn":"9800007788"
"TransactionId":"201609271720522269",
"ResponseDescription": "Success"
Response JSON values will be as below:
{
"MerchantCode":"M0001",
"RefId":"Ref-9901",
"TokenId":"201612151220041022",
"ResponseCode":"0"
}
ResponeCode: 0 -> Success
ResponeCode: 1 -> Not found or failed
Now, update the database table record created above identified by RefId with TransactionId,
Msisdn, and TranStatus with ResponseCode and StatusMessage with Response Description.
Step 6
After performing payment, the SDK will verify the payment. This feature is handled by the SDK
itself. On the basis of the validate payment response the merchant will get a response in
IMEPaymentCallback(). There are two types of responses that a developer can get in
IMEPaymentCallback
Response Code 100: Transaction was successfully executed and verified.
Response Code 101: Transaction request was successfully sent, but could not get verified.
The customer executing the payment will get an SMS for the confirmation.
9
Step 7
If merchant’s delivery URL is not called by IME Pay system, then merchant needs to recheck
the transaction status by calling recheck API with the parameters stored in step 3.
API URL to recheck confirmation https://stg.imepay.com.np:7979/api/Web/Recheck with type
=”POST”.
Also Authorization header and Module* should be sent to API for authentication purpose. The
same Apiuser and password as in step 1 should be used in header.
Authorization = Basic {Apiuser:Password} *
Module = {Module} **
NOTE:
* Values should be encoded using Base64.
** Module will be provided by IME pay.
Request JSON parameters will be as below:
{
"MerchantCode":"M0001",
"RefId":"Ref-9901",
"TokenId":"201612151220041022",
}
Response JSON values will be as below:
{
"ResponseCode":"0",
"Msisdn":"9800007788"
"TransactionId":"201609271720522269",
"ResponseDescription": "Success"
}
ResponeCode: 0 -> Success
ResponeCode: 1 -> Not found or failed
Now, update the database table record created above identified by RefId with TransactionId,
Msisdn, and TranStatus as response code and StatusDetail as Response Description.
10
Contacts
BUSINESS
Rita Pokharel– Sr. BDO
[email protected]
Ph. 9801190865
Rajesh Shrestha - Business Analyst
[email protected]Ph. 9801190734
TECHNICAL
Sameer Neupane – Integration Engineer
[email protected]
Ph. 9801191163
11
