Mswipe WisePad API4.0.0 Integration Guide Android Version

Mswipe WisePad API Integration Guide Android Version
Sep 08 2015
Version 4.0.0
Version History
Version History
Version Date Description
1.0.0 Initial draft.
1.0.2 Nov 29 1.Implemented the Fall back, for a defective chip
card, the SDK prompts to user Mag again in this
scenario ignores the checking for service code.
2. Fail back, once the transaction is submitted to
the and in case the card rejects or its been
removed before sending the issuer script back to
the card, then do a auto fail back.
3.Added the API description for
AutoVoidReversal and Change Passowrd, and
Last Trx status.
4.Fixed the issue EMV card sale API.
1.0.3 Feb 06 Included additional API for Void,History,

DeviceInfo, CashSale, BankSale, PreAuth.
2.0.1 March 19 1.The Bluetooth connection are optimized.
2.Implemented the PreauthCompletion.
3.moved the readTlv and readBatchData api,

please refer onRequestOnlineProcess on
ReturnBatchData in the example file
MswipeWisepadDRDTestSDKApp.
4.Bothe the development and Producation

enviroments can be enabled using the same
SDK.The environment to be used for configured
the SDK has to be specified in the constructor of
the MswipeWisepadController.
2.0.2 1.Changed the signature of the API calls

CreditSale_MCR
PreAuth_MCR
SaleWithCash_MCR
CreditSale_EMV
PreAuth_EMV
SaleWithCash_EMV
2.Added a function
resetWisePadSwiperController which will bring
the wise pad to idle which is ready state.
3. CheckCardResult.MCR_AMEXCARD listener
1
notification for accepting pin for the Amex card.
4.Moved the re-initialization of
2.0.3 Implemented the function cancelCheckCard
which would bring the wisepad device state from
Swipe or insert/Card state to ready state.
2.0.4 1. static void
setMACADDType(NETWORK_TYPE
networkType)
This function is build into the sdk which enables
to get the Ehternet or Wifi Address based on the
parameter that is been set. Its has a static access
so additional measure has to be taken for its value
to be persistent (Refer the example file for more
information)
2.0.5 The Api CreditSale_MCR,CreditSale_EMV will

return addinol prameters MID,TID,BatchNO.
The API Set_VoidCardSaleTrx returns the date
for the void transaction performed.
Proper error messages format for all the net work
issues.
2.0.6 Fixed the issue for auto reversal transaction.
The api LastTrxStatus return additional
parameters MIT,TID,BatcNo
3.0.0
Included additional API :
1. getCashHistory returns the latest Cash History

data
2. getBankHistory returns the latest Bank History

data
3. getCashSummary returns the Cash Summary of

selected date
4. getBankSummary returns the Bank Summary

of selected date
Modified existing API:
1. SaleWithCash_MCR added new parameter

totalAmount
2. CreditSale_EMV added two new parameters

mTVR and mTSI
3. PreAuth_EMV added two new parameters

mTVR and mTSI
4. SaleWithCash_EMV added three new

parameters totalAmount, mTVR and mTSI
4.0.0 Included additional API
1. Emi transactons .
2
2. Convenience fees transactions.
3. startMswipeGatewayConnection and
stopMswipeGatewayConnecton.
4. Duplicate transaction check enabled.

Restricts the same unique transaction.
3
License
System Requirements
Development Platform: JDK: Java 1.6 or above
Target System: Devices with Bluetooth v2.1
OS: Android 2.2 or above
CPU: 600MHz
RAM: 512MB
Overview
Mswipe’s WisePad is a payment card reading device that works with mobile
devices such as mobile phones. It has a magnetic card reader to read magnetic stripe
cards and also a smart card reader to read EMV chip cards. It can also accept a PIN from
the cardholder for Chip-and-PIN transactions. The LCD display is used to provide
feedback to the user. WisePad has an internal battery that can be recharged via a standard
mini USB connector.
WisePad communicates with the host mobile device through Bluetooth 2.1. Please
note that BLE is a subset of Bluetooth 4.0 specifications with an entirely new protocol
stack for rapid build-up of simple links which is compatible with Bluetooth 2.1 devices.
The host device must be able to support either Bluetooth 2.1 in order to work with
WisePad. In the SDK, the set of Bluetooth supports the Bluetooth 2.1 mode (indicated by
BTv2).
This document provides the guideline on how to integrate WisePad into their
mobile payment application (or App) to accept either magnetic or EMV cards.
Most importantly for the mobile application to communicate with the Mswipe
WisePad, the Mobile device has to be paired first this is kind of accepting or entrusting
each other. Once the device have entrusted each other and established a secure channel to
communicate, the application will have to just connect and can start sharing the data
between the devices and disconnect the communication link once the connection is not
required.
The sequence of steps needed for established the communication link between the
Mobile and WisePad are discussed in detail, please refer Bluetooth Pairing.
4
Android Permission
The library needs permission to use the Bluetooth and Network resources. The following
lines must be added to the AndroidManifest.xml file in the app project.
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.android.app.myapp" >
...
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"
/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
</manifest>
Mswipe WisePad API Integration
The API distributed through the library file(MswipeWisepadDRDSDK.jar) need

to be included in the Projects build path, please refer the sample example code
application(MswipeWisepadDRDTestSDKApp) which demonstrate the integration of the
API and the way blue tooth communications are performed. And another Sample file
included with solely shows the EMV and MCR processes which are discussed briefly in
the following sections.
Specially refer the CardSaleView.java file the way the Bluetooth connections, and
the IC and MCR cards are processed.
Highlighted below the important step by step process flow that would help in
integrating and understanding the blue-tooth connection, and executing the Debit or
Credit EMV card transactions and the information exchange between the WisePad and
the Android application.
Firstly the Mswipe WisePad device has to be paired to the mobile device, after
which the application can connect using the device address fetched from the paired list.
The below are the step that describe the various procedures that involve between the
Mobile application and the WisePad device.
5
1) The MswipeWisepadController Class
The MswipeWisepadController class is the core of this API library. It has a

number of general and utility methods that manage the class itself and a number of
methods that communicate with the WisePad device through the Bluetooth channel.
Communications between the phone and WisePad are bi-directional and both sides can
initiate a communication. When commands are sent to the App from the WisePad, the
MswipeWisepadController will receive them and delegate functions will be triggered
asynchronously.
When a command is initiated by the App, because of the nature of the

communication channel and the operations, some methods will require a longer time to
finish. To avoid blocking the App, all the methods are handled asynchronously. Delegate
handler methods are used to obtain the results and they are all prefixed by “on”, e.g.
onBTv2Connected().
2.Instantiation
An instance of a MswipeWisepadController must be created first. There should
not be more than one instance at any moment.  When the MswipeWisepadController
instance is no longer used, it should be disposed properly.
To initiate the wise pad communication the method initMswipeWisePadDevice has to

be called this would enable the EMV and MCR transaction between the WisePad and the
application and at moment the WisePad can be brought to a known initial state by using
the method resetWisePadController.
3. Development and Live Environment

The development and the live environment configuration are preset in the same
application, by default the application connects to the development environment, and the
title of the WisePadSDKTest Application is marked with Labs suggests the Labs
environment.
The type of environment should be configured by the host application and this
valued has to passed to the Mswipe Wisepad Sdk.
The user can change the environment to live or development by using the “Server
Environment” option from the menu list.
6
4.General Methods
Description
Method
MswipeWisepadController Constructor Method, that will instantiate the class and further
will allow accessing all the features of the WisePad.
Check if the WisePad already established a connection to the

isDevicePresent
Android device
Reset the controller to a known initial state.

resetWisePadController
5.Methods to communicate with WisePad
Method Name
Description
Start the Bluetooth connection with Bluetooth V2.0, you could

either choose the device from the paired device directly to connect,
or scan through the list of specific devices discoverable after the
devices are discovered the paring process are initiated and once
successful the devices are connected.
startBTv2
If the selected paired device is not a WisePad the SDK disconnects
and notifies the application through onDeviceDisconneted.
Supplying the friendly name to this function can scan specific

devices. If any of the devices are detected the pairing process are
initiated with in the application and once the paring process is
successful the device is connected.
7
stopBTv2
Stop the Bluetooth connection with Bluetooth V2.0
Retrieve parameters about the WisePad device. Results are returned

getDeviceInfo
by onReturnDeviceInfo.
Set the amount required for EMV transaction. This can be done
before the startEmv command or in response to
setAmount
onRequestSetAmount,
cancelSetAmount Cancel the EMV process at the set amount step.
Check if a card has been inserted or swiped. Results are returned by

onReturnCheckCardResult.
checkCard If the detected card is an EMV then the startEMV has to be called to
initiate the EMV process, if you know if the card is an EMV you
could directly use StartEMV this would speed up the EMV
transaction process.
Stop the check card process. This will be effective only before the
cancelCheckCard card has been inserted or before the WisePad has detected the card.
startEmv Start an EMV transaction. After receiving this command, WisePad

will take control and execute the EMV operation flow.
Select an application from a list of applications acceptable by the

selectApplication
terminal and the EMV card in response to
onRequestSelectApplication.
cancelSelectApplication Cancel the process in response to onRequestSelectApplication,

this would cancel the transaction.
sendTerminalTime Send terminal time to WisePad in response to

onRequestTerminalTime.
Send confirmation to WisePad in response to

sendFinalConfirmResult onRequestFinalConfirm, here you could cancel the EMV process,
before submitting the data which is triggered through the listener
function onRequestOnlineProcess.
8
Here the WisePad waits for the results of the data that is submitted
to the payment gateway for processing the transaction amount, and
the issuer script sent by the Card Schemes should be sent back to the
EMV card using sendFinalConfirmResult.
onRequestOnlineProcess For example the data issuer script 8A023030 which the EMV card
always approves, different card schemes have different issuer scripts
these have to be sent back to the EMV, the scripts are validated for
deciding to either approves or rejects the Transaction.
Sending null will invalidate the transaction, and the transaction is

declined and this will throw up as a message to the application.
Send referral results from the processor back to WisePad in

sendReferProcessResult
response to onRequestReferProcess.
cancelReferProcess Cancel the EMV process at the referral request step
Send transaction results i.e the issuer script back to WisePad in

response to onRequestOnlineProcess.
sendOnlineProcessResult The issuer script of the card schemes have to be notified back to the
card, and the WisePad does authenticate the script and either it
rejects or approves the transaction, and these are notified to the
Application through the onReturnTransactionResult.
The constructor method of the MswipeWisepadController class is the input

parameter passed must implement the interface MswipeWisePadDeviceListener which
has methods to handle different asynchronous events that occur during the operation of
the WisePad. The developer must design a class that implements the interface and pass an
instance of the class to the constructor method.
9
6.MswipeWisePadDeviceListener
public MswipeWisepadController (Context context,

MswipeWisePadDeviceListener MswipeWisePadDeviceListener)
Method Name
Description
WisePad has sent back the getDeviceInfo result

onReturnDeviceInfo
WisePad is waiting for card swipe or insert after

onWaitingForCard checkCard
WisePad has responded to startEmv

onReturnStartEmvResult
WisePad has sent back the checkCard result, here the card
onReturnCheckCardResult is detected if the card used is either EMV or MCR.
WisePad has requested user to insert EMV card.

onRequestInsertCard
WisePad has requested the user to select the application in

onRequestSelectApplication
the EMV process
WisePad has requested the user to enter the amount in the

onRequestSetAmount
EMV process. Here you could set the amount
WisePad has sent back the confirm amount result.

onReturnAmountConfirmResult
WisePad has requested the user to enter the PIN in the

onRequestPinEntry
EMV process
WisePad has sent back the PIN entry result, if the pin has
onReturnPinEntryResult
been entered it returns pin entered and along with the
encrypted pin block data.
onRequestTerminalTime
WisePad has requested the terminal time.
10
onRequestCheckServerConnectivity
WisePad has requested for a check of server connectivity
onRequestAdviceProcess WisePad has requested for advice processing
WisePad has requested for a final confirmation before it

starts initiating the EMV process transaction, here the user
onRequestFinalConfirm
will have last check before deciding to continue or to
cancel the EMV transaction.
WisePad has requested for online processing, the wise pad

has been initiated to execute online transaction, it will
onRequestOnlineProcess
output the card holder information all the information is
encrypted, the data can be submitted to the payment
gateway to perform the selected transaction amount.
onRequestReferProcess
WisePad has requested for referral processing
WisePad has requested to display information to the user,

onRequestDisplayText the various communications steps between the Mobile
Device,WisePad and the card are notified to the
application.
WisePad has sent the final transaction result from the EMV
card.
Once the issuer script is notified back to the EMV card it

onReturnTransactionResult responds the status of the transaction. In case if the
transaction has been approved online(the payment
gateway) and incase if the EMV card rejects it would
notify the user to perform an AutoReversal through the
function onReturnReversalData
onReturnTransactionLog
WisePad has sent back the transaction log.
onReturnReversalData
WisePad has sent back the reversal data
onReturnBatchData WisePad has sent back the batch data, after the issuer
script has been sent back to the EMV card for further
11
validation, the WisePad responds back with the TSV and
TSI for the transactions this will the have the information
related to the transaction.
onBTv2Detected
If the Mobile device has detected the WisePad device.
A WisePad with Bluetooth is connected via Bluetooth, and

onBTv2Connected this will respond with the connected Bluetooth address,
and the same can be used to connect back to the same
device.
onBTv2Disconnected
A WisePad with Bluetooth is disconnected.
onBTv2DeviceNotFound No WisePad with BTv2 is detected
The battery level WisePad is low or critically low. It can

occur after startEmv or getDeviceInfo. When the level is
onBatteryLow
low, the normal response will still happen. If the level is
critically low, the normal response will not occur.
Incase of any erroneous communications behavior between

onError the WisePad and Android Application are communicated
back to the applications and based on the type of error been
detected can be presented to the user.
7.Reset
At any time, the WisePad can be reset and brought back to a known initial state
by using the method resetWisePadController.
8.Bluetooth Pairing
The host mobile device and the WisePad must be paired before a communication
link can be established. One host device can only be paired with one WisePad.
12
9.Communication Link
To communicate with the WisePad, a communication link has to be established
first. This can be done connecting to the WisePad via Bluetooth.
To connect the WisePad with BTv2, call the method startBTv2 which takes a list of
device names it want to connect or a BluetoothDevice object. When a WisePad with
BTv2 is detected, the onBTv2Detected delegate method will be triggered and connecting
will be attempted. The WisePad is ready for communication after the onBTv2Connected
event.
When the communication link is no longer required, call the method stopBTv2
respectively to release the resource and unregister some related events. This method can
also be called after startBTv2 to terminate the scanning and connecting process.
Any commands that try to communicate with the WisePad before the communication link
is established will result in the error event onError:
COMM_LINK_UNINITIALIZED.
Note: For the BTv2 samples, the device name to match is “iBT-02”.
10.Power On/Off
The WisePad is normally powered down to minimize power consumption and it
must be switched on first.  The WisePad will enter power down mode after a certain time
span of inactivity (5 minutes).
11.Check Status of Device

Information of the device can be obtained by getDeviceInfo(). The device info is
returned by a hashtable through onReturnDeviceInfo().  The checkCard() is called to
see if a card has been swiped or inserted. The status is returned by
onReturnCheckCardResult(). If a card swipe is detected, the card data are also
returned.
12.Start EMV
The startEmv command can be called to start the EMV directly if the card to be
used is just an EMV this would speed up the EMV initiation and this would skip the
onCheckCardResult process.
If an EMV card has been inserted, the WisePad will take control and go through the
EMV steps.
13
13.EMV Process flow
EMV Card setup

Initialize the SDK/App process
WisePad
startEMV
startEmv startEmv
onRequestInsertCard
checkCard
checkCard checkCard
onReturnCheckCardResult
Is EMV Card
onReturnCheckCardResult startEmv
Failed to detect the card
o
n Failed to detect the card
onReturnStartEmvResult
R
et
u
r o
n Success
n
St R
a et
rt u
E EMV process
r
m n
v St
R a 14
e rt
s E
EMV Card
SDK/App Process WisePad
onRequestSetAmount
setAmount
setAmount Use press Confirm
amount button
onReturnAmountConfi
rmResult
2
onRequestSelectApplication
selectApplication
selectApplication Read and select
application
onRequestPinEntry 3
Pin entry onReturnPinEntryResult Enter or cancel pin
onRequestFinalConfirm
4
Cancel/Continue sendFinalConfirmResult onRequestFinalConfirm
onRequestOnlineProcess
5
Submit the details to If it’s a OnlineCard
gateway for processing sendOnlineProcessResult
Validate Issuer Script
15
Issuer Script process 6
sendOnlineProcessResult
Approved
onReturnBatchData
Offline
Declined
onReturnReversalDa onReturnTransactionResult 7
ta
o Failure reason
n
R
et
u Complete
r
n
St
a
rt Remove Card
E
m
v
R
e
EMV Step 1. Starts EMV
ul
Start EMV,  If ant EMV card is not detected, the onRequestInsertCard() is triggered
prompting the user to insert an EMV card.
A transaction amount is needed for a payment transaction and it to be entered by the

operator (or calculated by the inventory system). The onRequestSetAmount() delegate
method is triggered.
The app should prompt the operator to enter the amount, cashback amount, currency code
16
and transaction type and then call the setAmount() to send the data back to WisePad. The
user can also select to abort the transaction.
EMV Step 2. Select Application

An EMV card may support multiple payment applications. The WisePad reads the
list of applications supported by the EMV card and asks the customer/operator to select
the desired application.
The delegate method onRequestSelectApplication() is triggered to return an

array of application IDs. The app should prompt the user to select one application and
then call the selectApplication() method.
The user can also select to abort the transaction by the command
cancelSelectApplication().
In most cases, there is only one default application and this step can be handled by
the app but selecting the first application by default.
3.EMV Step 3. Card Authentication

This step is only done between the WisePad and EMV card. If this step fails,
onReturnTransactionResult() will be returned and the EMV process stops.
There are different cardholder verification methods (CVMs) supported in an EMV

transaction and some require the customer to enter a PIN (personal identifier number). If
the EMV transaction requires PIN verification, the customer must enter his PIN.
In this step, WisePad will request PIN entry from the user by
onRequestPinEntry(). The client app should display the instruction for PIN entry. The
PIN is captured on the WisePad.
Some applications (e.g. for small amount payment) does not require CVM
(Cardholder Verification Method) and this step is skipped.  But it is also possible that the
EMV card decline a transaction without PIN.
4.EMV Step 4. Final Confirmation

This step is done between the WisePad and EMV card. If this step fails,
onReturnTransactionResult() will be returned and the EMV process stops. At the end
of this step, a final confirmation will be needed to proceed via
onRequestFinalConfirm().
17
The app should prompt the user for a confirmation to proceed. This gives the user
a chance to review the amount, the payment method, etc. The final confirmation is sent to
WisePad by calling sendFinalConfirmResult().
5.EMV Step 3. Online Processing

An EMV transaction can either be online or offline.  If online processing is
required, then the onRequestOnlineProcess() delegate method is triggered. The EMV
data are returned in a tag-length-value (TLV) data structure by the EMV kernel.
After that, the client app should send the data to the processor. When the
processing results, also in TLV format, are returned from the processor, it should send the
results back to WisePad by sendOnlineProcessResult().
The data elements that are required are processor and issuer dependent. See the
EMV Book 3 Annex A for the full list of tags and the TLV structure.
The following tags are usually required but are ICC dependent:
Tag
Parameter
008A
Authorization Response Code
0091
Issuer Authentication Data
0071 Issuer Script Template 1 (needed for Step 10)
0072 Issuer Script Template 2 (needed for Step 10)
This step is skipped in offline processing.
6.EMV Step 3. Issuer Scripts Processing

This step is handled transparently between the WisePad and EMV card if issue
scripts are present in the online processing results or skipped otherwise.  This step is
18
skipped in offline processing.
7.EMV Step 3. Completion

In this step, WisePad sends back the final transaction result from the EMV card
by onReturnBatchData(). The client app should store the batch data results, display the
results, print receipts, and prompt the user to remove the card from the WisePad device.
Later, the batch data should be updated to the server for settlement.
19
14.Magnetic Card Flow
The operation for magnetic stripe operation is much simpler.  If a card has been
swiped successfully, the data are returned in a table containing the encrypted card data
through the method onReturnCheckCardResult(). With these parameters, the track data
can be decrypted back in the server.
MCR Card process

Initialize the SDK/App WisePad
onWaitingForCard
checkCard
checkCard checkCard
onReturnCheckCardResult
Is MCR Card
onReturnCheckCardResult Successful
o
n
20
15)Bluetooth Communications
Bluetooth
Connection Initialize the SDK
StartBtv2 StartBtv2
Scanning the specified Connecting through

friendly name the paired device
No Devices found
onBTv2DeviceNotFound
Initiates the pairing

with the found devices
and tries to connect.
Device switched off.
If the device is not a

onDeviceDetected wisepad
onBTv2DeviceConnected
OnError-FAIL_TO_START_BTV2
stopBtv2
Pairing can
onBTv2DeviceDisConnected WisePad idle for 5 minutes
Powerdown or
Switched off 21
be established from the Device system setting or directly form the Application, the
preferred option is to set it outside of the application.
From the application pairing can be achieved using the function call
startBTv2(new String[] {"WisePad"}).This will scan the devices using the friendly name
of the device which is WisePad and will step through the paring process and prompts for
the pass key which has to be confirmed by the both devices which are involved.
The WisePad device can be paired by any no of devices, when a Application is

connected, the device goes to non discoverable mode as it accepts only one connection,
for any reason if the application is not able to connect, use the button next the power
switch on/off button which enables the device into discoverable.
2)Connection
The fasted way to connect to the WisePad device from application is using the
device Mac address from the paired list.
The paired device lists are available to the application but the friendly names are
not guaranteed to be unique. To filter the exact device from the paired list, a Mac address
can be used, this is available to the application when a successful connection is made to
the device through the listener function onBTv2Connected(BluetoothDevice
bluetoothDevice).
Once you have the Bluetooth device address or object from the paired list, a
connection can be established using the function startBTv2(BluetoothDevice
bluetoothDevice).
At any given moment from the application the status of the application can be
checked using the function isDevicePresent.
3)Disconnect
When the application no more needs the connection it should disconnect it self
from WisePad, the function that is available for performing this is stopBTv2. This will in
fact restart the WisePad device and flushes all the transaction from the cache, so at any
time when a connection is made to the device the application has to make sure to
disconnect, this is required since the device will go into un-discoverable mode until the
application disconnects from this device.
The application can close it self in many ways in Android, like when the
application goes to background either when another application get a priority for ex the
phone call, or when the home button is pressed, or when it is closed specifically by the
user, in this scenarios the application has to make sure to disconnect from the WisePad,
please refer the test sample application the way this is achieved.
22
16)PayMent Gateway Process
The API described below will enable the online payment process, which transacts
the information of EMVor MCR card used and submits to the online payment gateway
for further validating the authenticity of the cards and communicated back to the
application.
The user here called as Merchant should have to login or identify himself to the
system first to be able to access the online payment gateway API’s.
All the connection to the Mswipe server are persistence, prior to calling up the
Web method the connection to the Mswipe server can be initiated, as this involves a
complex ssl negotiations, so opening up the connection to Mswipe server would
tremendously reduce the transaction process lag.
The persisted connection need to be closed when the connection is no more

required, this can be achieved using the API functions startMswipeGatewayConnection
and stopMswipeGatewayConnections this are methods asynchronously initiates the
connection process and are notified back to the calling object interfaces, please refers the
sample application where the connection are opened in onStart, and closed in onStop.
1.Payment Gateway Architecture
23
1. Persistent Mswipe Gateway connection
startMswipeGatewayConnection
To improved the overall performance of the transaction the connection to the
Mswipe sever can be initiated prior to calling up the Web methods, for instance in the
sample application the connection are been opened up in the onStart function by using
the startMswipeGatewayConnection method this initiated the connection in the back
ground and the status of the connection are delegate asynchronously.
MswipeWisePadGatewayConnectionListener
The interface object through which the status of the connectin are notified to this
listener object.
startMswipeGatewayConnection
When the connection in no more required its essential to stop the connection, as
this will release the resources on the server.
2. Merchant Authentication
Description :
This API will authenticate and identify the Merchant in MSwipe database, on
successfully authentication the API will return the details of the Merchant which are
mentioned below and the resultant data is needed for calling the other services, so its
important to save specifically the Session_Token and the Reference_id, the
Sessoin_Token is the digest identifying the user.
The Session_Token and Referenec_id are unique, and the Session_Token remains
the same until the password is changed. These details can be stored and can be used
further for accessing the other API’s.
Method :
public void AuthenticateMerchant(Handler loginHandler, String aUserId,
24
String aUserPassword);
Parameters :
1) aUserId
The user id of the Merchant.
2) aUserPassword
The password of the Merchant.
Returned Parameters :
The function returns the result using the asynchronous function Handler, is the
first parameter to the API, the API response is of the form XML, the resultant XML will
have all the formatted information of the user Authentication details stating if the
execution of the function is a failure or success.
Parameters :
1) Handler loginHandler
Additional information is notified from the Mswipe server to the Handler as an
XML, the format of the XML is as follows.
a)<ResultElement>
<status>False</status>
<ErrMsg>Incorrect user id for this mobile</ErrMsg>
</ResultElement>
If The xml tag status is false, suggests the function failed to execute successfully
and the exact reason of the failure is send in the other tag i.e ErrMsg.
b)<ResultElement>
<status>True</status>
<IS_Password_Changed>false</IS_Password_Changed>
<First_Name>John Smith</First_Name>";
<Reference_Id>10514789</Reference_Id>";
<Session_Tokeniser>xxxxxxxxxxx</Session_Tokeniser>
<Currency_Code>INR</Currency_Code>";
<IS_TIP_REQUIRED>True/False</IS_TIP_REQUIRED>
<CONVENIENCE_PERCENTAGE>0.00</CONVENIENCE_PERCENT
AGE>
<SERVICE_TAX>0.00</SERVICE_TAX>
</ResultElement>
25
If the xml tag status is true, the other details of the User are sent as a response,
the details like Reference_Id and Session_Tokeniser have to saved as these are required
for calling the other services.
If IS_Password_Changed false will indicate the user has not changed is password
at-least once since he’s registration, it mandatory to change the user password at least
once to be able to use the other services.
IS_TIP_REQUIRED is true and if the convenience is not enabled for the user,
then the tip amount is added up to the sale amount and total added up amount will be the
total sale amount that would be debited from the card.
IS_TIP_REQUIRED is true and if the convenience is defined for the user, the
valued returned for this fields suggest that the convenience fees has to be charges, in this
case the tip amount is replaced by the convenience charges, the
CONVENIENCE_PERCENTAGE is applied on the sale amount, and then the
SERVICE_TAX is applied to the PERCENTAGE amount, the resultant total amount for
the sale is derived by adding this three values will be the final sale amount.
3. Magnetic Card Sale
Description :
This function will allow doing a Magnetic Card transaction, when the device is
initiated to check to see if Magnetic card is swiped using the function
WisePadController.checkCard(), this will read the track of the card and sends the details
to the Application, and this details have to be submitted to the payment gateway for
further processing.
If the Card swiped required a pin code, the device automatically detects and
notifies the user to input the pin key on the device, after confirming the key the
application is notified with the additional data through the listener function
onReturnPinEntryResult which are Epb and Epbksn, this data has to be sent to the issuer
bank for authentication. For a working example please refer the test application.
Method :
public void CreditSale_MCR(Handler cardSaleHandler,

String aReferenceId, String aSessionTokeniser,
String aReceipt, aAmexSecurityCode,
String aTotalAmount, String aBaseAmount,String aPhoneNo, String
aEmail, String aNotes, String aTipAmount, Boolean
isConvenienceFeeEnabled);
26
Parameters :
1) Handler cardSaleHandler

a) <ResultElement>
<ErrMsg>Invalid card.</ErrMsg>
</ResultElement>
If the xml tag status is false, suggests the function failed to execute successfully
b) <ResultElement>
<StandId>StandId</StandId>
<RRNO>RRNO</RRNO>
<AuthCode>AuthCode</AuthCode>
<Date>Date</Date>
</ResultElement>
If The xml tag status is true, then the transaction is approved by the getaway, and
the response details are needed for accepting a signature receipt from the purchaser.
2) aReferenceId
The reference id of the Merchant.
3) aSessionTokeniser
This data identifies the Merchant.
4) aReceipt (not mandatory)

Data representing the receipt id for the transaction, this is not mandatory.
5)aAmexSecurityCode
The four digits security code should be accepted for the AmexCard please refer
the sample application.
6) aTotalAmount,
The total is calculated based on if tip and convenience percentage are enabled.
a)If tip is enabled and convenience is not defined i.e 0. Them the totalAmount is
the sum of aAmount and tipAmount.
27
b)If tip is enabled and convenience is defined i.e >0, then the totalAmount is
the sum of Convenience Percentage calculated on the base amount and the service
tax computed on the Convenience percentage amount.
c)If tim amount is not enabled then the tipAmount should have the value
0.00, and the parameter isConvenienceFeeEnabled shoule be set to false.
7) aBaseAmount,
The orginal amount of the transaction, and the total amount is calculated applying
the tip amount and the convenience fee, which ever is applicable,
8) aPhoneNo
The mobile no of the purchaser, an SMS will be sent to the provided no, the
mobile no has to prefixed with the country code, for ex if the no is from India it should be
sent as +91 9999999999
9) aEmail (not mandatory)

Email address of the purchaser, a receipt would be sent to the email provided.
10) aNotes (not mandatory)
Notes or remarks for the transaction.
11) aTipAmount
If tip amount is enabled, this amount is added to the based amount for deriving the
total amount.
12) isConvenienceFeeEnabled
If the tip is enabled and the convenience fee is defined for the merchant then
isConvenienceFeeEnabled should be sent as true.
4. Card sale EMV
Description :
This function will allow to do a EMV or ICC Card transaction, when the device is
initiated to check to see if ICC card has been inserted using the function
WisePadController.checkCard(), this will read the chips which are hard wired on the card
and send the details to the Application, and this details have to be submitted to the
payment gateway for further processing.
Method :
public void CreditSale_EMV(Handler cardSaleHandler,
String aReferenceId,String aSessionTokeniser,
String aReceipt , String aTotalAmount, String aBaseAmount,
String aPhoneNo, String aEmail, String aNotes,
28
Stirng mTVR, String mTSI, String aTipAmount,
Boolean convenienceFeePercentage).
Parameters :
a) <ResultElement>
</ResultElement>
b) <ResultElement>
<RRNO>RRNO</RRNO>
<Date>Date</Date>
<F055tag>00</F055tag>
<EmvCardExpdate>Expdate</EmvCardExpdate>
<SwitchCardType>CardType</SwitchCardType>
<IssuerAuthCode>IssuerAuthCode</IssuerAuthCode>
</ResultElement>
If The xml tag status is true, represents an approved transaction by the getaway,
and the other details that are send back used for the signature receipt and the
IssuerAuthCode has to communicated back to the EMV card which validated the script.
2) aReferenceId
29
5) aTotalAmount,
The total is calculated based on if tip and convenience percentage are enabled.
a)If tip is enabled and convenience is not defined i.e 0. Them the totalAmount is
the sum of aAmount and tipAmount.
b)If tip is enabled and convenience is defined i.e >0, then the totalAmount is
the sum of Convenience Percentage calculated on the base amount and the service
tax computed on the Convenience percentage amount.
c)If tim amount is not enabled then the tipAmount should have the value
0.00, and the parameter isConvenienceFeeEnabled shoule be set to false.
6) aBaseAmount,
The orginal amount of the transaction, and the total amount is calculated applying
the tip amount and the convenience fee, which ever is applicable
7) aPhoneNo
sent as +91 9999999999


10) TVR
Terminal verivication response code value set from the tlv data parsered in the
delegate function onRequestOnlineProcess.
11) TSI
Transaction status information response code value set from the tlv data parsed in
the delegate function onRequestOnlineProcess.
12) aTipAmount
If tip amount is enabled, this amount is added to the based amount for deriving the
total amount.
13) isConvenienceFeeEnabled
If the tip is enabled and the convenience fee is defined for the merchant then
isConvenienceFeeEnabled should be sent as true.
30
5. Generating Signature Receipt
Description :
A card holder has to be verified by capturing his signature through the
device, using the scribbled signature of the purchaser this function will super impose the
other details like Name , Trx date , and Last four digits to the Signature bitmap image
passed as a parameter.
Method :
public void UploadSignature(Handler cardSaleSignatureHandler, String aReferenceId,

String aSessionTokeniser, String aLstFrDgts, String aAmt,
String aStandId, byte[] aEncodedImage,String aTVR, String aTSI)
Parameters :
1) Handler cardSaleSignatureHandler
Additional information is notified from the Mswiper server to the Handler as an
a) <ResultElement>
</ResultElement>
b) <ResultElement>
</ResultElement>
If The xml tag status is true, suggests that the signature has successfully processed.
2) aReferenceId
31
4) aLast4Digits
Last four digits of the card.
5) aAmount,
The amount for the transaction.
6) aStandId
The Stain Id for the Card sale transaction.
8) aEncodedImage
Bitmap image of the signature stroked on the device.
9) aTVR
TVR of the transaction, this data is extracted from the TLV data sent by the
onReturnBatchData function.
10) aTSI
TVR of the transaction, this data is extracted from the TLV data sent by the
onReturnBatchData function.
6. Auto Reversal for void

Description :
Auto reversal for void has to performed when the Card rejects the
transaction when the Issuer script is submitted back to the Card, here the SDK notifies the
application with the onAutoReversalProcess event, then the details like FO55 tag has to
be send back to the gateway for initiating the void process. In two particular scenarios the
Auto reversal has to be performed.
1. Offline decline
When the card rejects the transaction, here a parameter E1 has to sent
suggesting it an offline declined.
2. Fail Back
This occurs when the IC card inserted is pulled back before the issuer
Script has been sent to the card, the SDK notifies the event through the callback function
onAutoReversalProcess, the parameter E2 has to sent suggesting its an fail back
transaction.
Method :
32
public void AutoReversalCardSaleTrx(Handler cardSaleAutoReversalHandler, String
aReferenceId, String aSessionTokeniser, String aTrxDate, String aTrxAmount,
String aLast4Digits, String aStanId, String aF055Tag,String aOfflineDeclineTag);
Parameters :
1) Handler cardSaleAutoReversalHandler
a) <ResultElement>
</ResultElement>
b) <ResultElement>
</ResultElement>
If The xml tag status is true, suggests that the signature has successfully processed.
2) aReferenceId
4) aTrxDate
The date of the transaction, the date that was sent by the card sale for emv and
mcr has to be used here, and the date format should of the form YYYY-MM-DD.
5) aAmount,
4) aLast4Digits
Last four digits of the card.
6) aStandId
33
The Stan Id for the Card sale transaction.
7)F055 tag
This is the tag that was returned by the Card sale for emv, the same data has to
sent back to the this funcation.
8) aOfflineDeclineTag
This data shoule be either E1 or E2, please refer the example the way this
parameter has be intitialized.
7. Last Transaction status

Description :
Would return the details of the last transaction that was performed by the
user.
Method :
public void LastTrxStatus(Handler lstTrxStatusHandler, String aReferenceId,

String aSessionTokeniser);
Parameters :
1) Handler lstTrxStatusHandler
a) <ResultElement>
</ResultElement>
b)<ResultElement>
34
<TrxDate></TrxDate>
<CardHolderName></CardHolderName>
<CardLastFourDigits></CardLastFourDigits>
<TrxAmount></TrxAmount>
<TrxType></TrxType>
<TrxNotes></TrxNotes>
<VoucherNo></VoucherNo>
<AuthNo></AuthNo>
<RRNo></RRNo>
<StanNo></StanNo>
<TrxStatus></TrxStatus>
<TerminalMessage></TerminalMessage>
</ResultElement>
If The xml tag status is true, suggests that the function has successfully processed, and
the additional data of the transaction.
2) aReferenceId
8. Password Change
Description :
The will enable to the change the existing password, when this API
successfully changes the password it will send out the new SessionTokeniser, this has to
preserved and has to used for calling the other services.
Method :
public void ChangePassword(Handler changePwdHandler, String aPassword, String

aNewPassword, String aReferenceId,
Parameters :
1) Handler changePwdHandler
35
a) <ResultElement>
</ResultElement>
b)<ResultElement>
</ResultElement>
If The xml tag status is true, suggests that the function has successfully processed, and
the additional data of the transaction.
2) aReferenceId
4) aPassword
The original password.
5) aNewPassword
The password to be changed to.
9. Void Transaction
Description :
Any transaction can be voided, to invoke this API the Amount of the
transaction and the Last four digits of the card used are required, the Void is a two steps
process, first by using the details will fetch the Voucher and Stand Id of the transaction,
and these details have to posted using the API Set_VoidCardSaleTrx to complete the void
process.
Method :
public void Get_VoidCardSaleTrx(Handler VoidCardSaleHandler, String aReferenceId,

String aSessionTokeniser, String aTrxDate, String aTrxAmount,
String aLast4Digits);
36
public void Set_VoidCardSaleTrx(Handler VoidCardSaleHandler, String aReferenceId,
String aLast4Digits,String aStanId, String aVoucherNo);
Parameters :
1) Handler VoidCardSaleHandler
a) <ResultElement>
</ResultElement>
b)<ResultElement>
<TrxDate> date</TrxDate>
<StandId> StandId </StandId>
<Voucherno> Voucherno</Voucherno>
<CardLast4Digits>CardLast4Digits</CardLast4Digits>
<TrxAmt>TrxAmt </TrxAmt>
<AuthNo> AuthNo</AuthNo>
<RRNO>RRNO</RRNO>
</ResultElement>
If The xml tag status is true, suggests that the function has successfully processed,
and the additional data of the transaction
c)<ResultElement>
<Msg>Approved</Msg>
</ResultElement>
37
If The xml tag status is true, suggests that the function has successfully processed,
and the additional data of the transaction
2) aReferenceId
4) aTrxDate
The transaction date of the card sale, it should be sent in the YYYY-MM-
DD format.
5) aLast4Digits
Last four digits of the cards that is used to for the Transaction.
10. Cash Sale & Bank Sale

Description :
The Cash sale and Bank sale transaction are very similar except for the
Bank Sale the Cheque date and no are required.
Method :
public void CashSaleTrx(Handler CashSaleHandler, String aReferenceId,

String aSessionTokeniser, String aReceipt, String aPhoneNo,
String aEmail, String aAmount, String aNotes);
public void BankSaleTrx(Handler BankSaleHandler, String aReferenceId,

String aSessionTokeniser, String aReceipt, String aPhoneNo,
String aEmail, String aAmount, String aNotes, String aChequeDate,String
aChequeNo);
Parameters :
1) Handler CashSaleHandler
a) <ResultElement>
</ResultElement>
38
b) <ResultElement>
<InvoiceNo>InvoiceNo </InvoiceNo>
<MID>mMID</MID>
<TID>mTID</TID>
<VoucherNo>mVoucherNo</VoucherNo>
<Date>mDate</Date>
</ResultElement>
2) aReferenceId
5) aAmount,
6) aPhoneNo
sent as +91 9999999999

39
11. History
Description :
The History function will fetch the latest 30 transaction of the user.
Method :
public void getCardHistory(Handler CardHistoryHandler, String aReferenceId,

Parameters :
1) Handler CardHistoryHandler
a) <ResultElement>
</ResultElement>
b) <ResultElement>
<Data>
<TrxDate>Date</TrxDate>
<CardLastFourDigits></CardLastFourDigits>
<TrxAmount>Amount</TrxAmount>
<TrxType>Void</TrxType>
<TrxNotes></TrxNotes>
40
<MerchantInvoice>Invoice</MerchantInvoice>
<StanNo>stanNO</StanNo>
<VoucherNo></VoucherNo>
<AuthNo></AuthNo>
<RRNo></RRNo>
<TrxStatus></TrxStatus>
<TerminalMessage></TerminalMessage>
</Data>
</ResultElement>
2) aReferenceId

12. Pre Auth Completion
Description :
The Pre Auth sale can be completed using this method, it’s a two step
process, firstly using the Last Four digits and the Amount of the Pre auth sale the details
like Date, Amount, Last4Digits , StanId, VoucherNo have to fechted, there could be any
no of Pre auth sale for a transaction using the same card and amount, these are returned as
an array of Objects, and each Object will have the information which has to be used for
performing the Pre Auth completion using the method Set_PreauthTrxCompletion.
Method :
public void Get_PreauthDetailsForCompletion(Handler VoidCardSaleHandler, String

aReferenceId,
String aSessionTokeniser, String aSelectedDate, String aTotal,
String aLast4Digits);
public void Set_PreauthTrxCompletion(Handler VoidCardSaleHandler, String

aReferenceId,
41
String aLast4Digits,String aStanId, String aVoucherNo)
Parameters :
1) Handler Get_PreauthDetailsForCompletion
a) <ResultElement>
</ResultElement>
b) Array of PreAuthData Objects.
Each element in the array is PreAuthData which will have the details
which are required for the PreAuthCompletion.
2) aReferenceId
4) aTrxDate
The transaction date of the card sale, it should be sent in the YYYY-MM-
DD format.
5) aLast4Digits
Last four digits of the cards that is used to for the Transaction.
13. EMI transaction
Description:
Using new included APIs for EMI user can now perform EMI transactions
using these APIs following are the description of EMI APIs
public void getEmiDetails(Handler emiDetialHandler, String aReferenceId,

String aSessionTokeniser,String afirst6Digits, String amount)
42
getEmiDetails: one can use this api to get available EMI options available for the card.
Parameters:
1) Handler emiDetialHandler
a) <ResultElement>
</ResultElement>
b) Array of Emi Objects.
Each element in the array is EMI data which will have the details which
are required for the EMI transaction.
2) aReferenceId
4) afirst6Digits
First 6 digits of the card.
5) amount
Emi amount.
public void EMI_MCR(Handler emiSaleHandler, String aReferenceId,

String aSessionTokeniser, String aReceipt,
String aAmexSecurityCode,String aAmount,String aPhoneNo, String
aEmail, String aNotes, String emiTenure, String bankCode)
Parameters :
1) Handler emiSaleHandler

43
a) <ResultElement>
</ResultElement>
If the xml tag status is false, suggests the function failed to execute successfully
b) <ResultElement>
<RRNO>RRNO</RRNO>
<Date>Date</Date>
</ResultElement>
If The xml tag status is true, then the transaction is approved by the getaway, and
the response details are needed for accepting a signature receipt from the purchaser.
2) aReferenceId

5) aAmount,
6) aPhoneNo
sent as +91 9999999999

9) emiTenure
44
Tenure of the selected EMI option, that we will get in “getEmiDetails” method.
10) bankCode
Bank code of the selected EMI option that we will get in “getEmiDetails” method.
public void EMI_EMV(Handler cardSaleHandler, String aReferenceId,

String aSessionTokeniser, String aReceipt, String aAmount,String
aPhoneNo, String aEmail, String aNotes, String mTVR, String mTSI,
String emiTenure, String bankCode)
Parameters :
a) <ResultElement>
</ResultElement>
b) <ResultElement>
<RRNO>RRNO</RRNO>
<Date>Date</Date>
<F055tag>00</F055tag>
<EmvCardExpdate>Expdate</EmvCardExpdate>
<SwitchCardType>CardType</SwitchCardType>
<IssuerAuthCode>IssuerAuthCode</IssuerAuthCode>
</ResultElement>
45
2) aReferenceId
9) aAmount,
10) aPhoneNo
sent as +91 9999999999


13) emiTenure
Tenure of the selected EMI option, that we will get in “getEmiDetails” method.
14) bankCode
Bank code of the selected EMI option that we will get in “getEmiDetails” method.
13. Device Info

Description :
The Bluetooth connection has to establishing the to the wise pad device,
before calling the getDeviceInfo() , this will output the device details using the
onReturnDeviceInfo call back function, refer the demo example.
46
47

Mswipe WisePad API4.0.0 Integration Guide Android Version

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Mswipe WisePad API4.0.0 Integration Guide Android Version

Hochgeladen von

Copyright:

Verfügbare Formate

Mswipe WisePad API Integration Guide Android Version

1.0.3 Feb 06 Included additional API for Void,History,

2.Implemented the PreauthCompletion.

3.moved the readTlv and readBatchData api,

4.Bothe the development and Producation

2.0.2 1.Changed the signature of the API calls

2.0.5 The Api CreditSale_MCR,CreditSale_EMV will

1. getCashHistory returns the latest Cash History

2. getBankHistory returns the latest Bank History

3. getCashSummary returns the Cash Summary of

4. getBankSummary returns the Bank Summary

Modified existing API:

1. SaleWithCash_MCR added new parameter

2. CreditSale_EMV added two new parameters

3. PreAuth_EMV added two new parameters

4. SaleWithCash_EMV added three new

4.0.0 Included additional API

4. Duplicate transaction check enabled.

Mswipe WisePad API Integration

The API distributed through the library file(MswipeWisepadDRDSDK.jar) need

The MswipeWisepadController class is the core of this API library. It has a

When a command is initiated by the App, because of the nature of the

To initiate the wise pad communication the method initMswipeWisePadDevice has to

3. Development and Live Environment

Check if the WisePad already established a connection to the

Reset the controller to a known initial state.

5.Methods to communicate with WisePad

Start the Bluetooth connection with Bluetooth V2.0, you could

Supplying the friendly name to this function can scan specific

Retrieve parameters about the WisePad device. Results are returned

cancelSetAmount Cancel the EMV process at the set amount step.

Check if a card has been inserted or swiped. Results are returned by

startEmv Start an EMV transaction. After receiving this command, WisePad

Select an application from a list of applications acceptable by the

cancelSelectApplication Cancel the process in response to onRequestSelectApplication,

sendTerminalTime Send terminal time to WisePad in response to

Send confirmation to WisePad in response to

Sending null will invalidate the transaction, and the transaction is

Send referral results from the processor back to WisePad in

cancelReferProcess Cancel the EMV process at the referral request step

Send transaction results i.e the issuer script back to WisePad in

The constructor method of the MswipeWisepadController class is the input

public MswipeWisepadController (Context context,

WisePad has sent back the getDeviceInfo result

WisePad is waiting for card swipe or insert after

WisePad has responded to startEmv

WisePad has requested user to insert EMV card.

WisePad has requested the user to select the application in

WisePad has requested the user to enter the amount in the

WisePad has sent back the confirm amount result.

WisePad has requested the user to enter the PIN in the

onRequestAdviceProcess WisePad has requested for advice processing

WisePad has requested for a final confirmation before it

WisePad has requested for online processing, the wise pad

WisePad has requested to display information to the user,

Once the issuer script is notified back to the EMV card it

A WisePad with Bluetooth is connected via Bluetooth, and

onBTv2DeviceNotFound No WisePad with BTv2 is detected

The battery level WisePad is low or critically low. It can

Incase of any erroneous communications behavior between

11.Check Status of Device

EMV Card setup

Failed to detect the card