The EMDK for Android provides developers with a comprehensive set of tools to easily create Payment application for use with the Symbol Technologies, Inc enterprise mobility device and PD40-100 payment device.
Enabling the payment device
The following requirements must satisfy before calling enable method to enable the payment device to do transactions.
By default the payment device (PD40-100) is not discoverable. If the user wants to manually pair the PD40 payment with the mobile device, PD40 can be made discoverable by pressing Enter + 9 on the PD40.
The recommended solution is for developer is to use to scan the barcode available on the backside of PD40 and programmatically pair the PD40 with the mobile device.
The payment device (PD40-100) must be paired to the mobile device before using the EMDK Mobile Payment APIs.
The application can get payment device object can obtained in the following ways:
Using device identifier to use first paired PD40 to the mobile device.
Enumerate the paired PD40 payment devices and use its device info
Using the device address. Providing friendly name involves Bluetooth device discovery to get the specified Bluetooth device. Establishing connection with payment device using MAC address will be quicker than friendly name.
The clients must implement the data listener interface and register for notifications. The status of the enable will be returned through the registered listener.
The application can call other methods only after the successful enabling of the payment device. It recommended that application must call the disable PD40 when the application does not require anymore which will allow other applications can use the payment device if needed.
Payment Device Configuration
The payment device settings can be configured using the PaymentDevice.getConfig and PaymentDevice.setConfig methods. The payment device must be enabled before calling getConfig and setConfig methods. As per the current PD40-100 payment device, all the parameters set are global across different application, but in the future PD40-100 binaries this will be made local to the application which configures the payment device.
idleMessage
The idle message displayed on the payment device can be configured by using idleMessage field in PaymentConfig.
sleepModeTimeout
The payment device PD40-100 has the default sleep mode timeout. Bluetooth connection with mobile computer will remain enabled even after PD40 goes to sleep mode.
The application can modify the default sleep mode time. Setting the sleep mode time out zero will turn off the device going to sleep mode. The turning off the sleep mode will consume the some power and the battery will discharge quickly.
getAllEncyptedData
When the Encryption is ON, readCardData will return encrypted track2 data for MSR and encrypted tag “57” data for EMV by default. To get the encrypted track1 and track2 data for MSR and encrypted tag “5A” data, getAllEncryptedData flag must be set to true before issuing calls to card data.
dataEncryptionType
By default the PD40-100 payment device returns the data in as clear text. If the payment application want to receive the card data encrypted data, this flag must be set the required encryption type if that encryption is supported by the payment device.
Configuring the Messages Displayed on the Payment Device.
The readCardData and promptPin method has overloaded methods one does not take any message and other provides an option to pass the message which will be displayed on the payment device. The payment application which wants use the default message defined by the payment device can call the method without any message. The payment application which wants to configure the message displayed on the can pass the message which be displayed on the Payment device.
EMV Transaction
For the EMV transaction, the card needs to be inserted until the transaction is completed and removing the inserted card while processing will lead to failure. When the transaction is completed, the payment application must call the removeCard to instruct the user to remove card. Also removeCard wipes out the EMV card data stored the payment device. So it is recommended to call the removeCard at the end of the EMV transaction.
PromptPin
The promptPin API will succeed only if the payment device is injected with debit key. When the promptPin is called, the payment device validates the last four digits of the account number against the previously read card data. The application can pass the maskedPAN returned by readCardData as input to account number in the promptPin.
GetEmvTags
Gets tag information from the inserted card. If there is no tag passed to D180, then all the TLV data according to predefined getEMVTags table will be returned. Tags Returned from getEMVTags could be found in the GetEMVTags Table.If there is(are) one(more than one) tag(s) passed to D180, then just the specific TLV data will be returned.
Specific tags can be defined in tagIDs as explained in the following.
For example:
ArrayList<String> emvTagData = new ArrayList<String>();
emvTagData.add("5F2A");
emvTagData.add("5F20");
emvTagData.add("82");
PaymentResults result = paymentDevice.getEmvTags(emvTagData);
GetEMVTags Table
Tag Identifier | Description |
---|---|
9F41 | Transaction Sequence Counter from terminal |
9F02 | Amount Authorized |
9F03 | Amount (other) (TIP) |
5F36 | Transaction currency component |
9F1B | Terminal Floor Limit |
9F1C | Terminal Identification |
9F35 | Terminal Type |
9F1A | Terminal Country Code |
5F2A | Transaction Currency Code |
82 | Application Interchange Profile Indicates the capabilities of the card to support specific functions in the application |
9F37 | Unpredictable Number Value to provide variability and uniqueness to the generation of a cryptogram |
9C | Transaction Type |
9F10 | Issuer Application Data |
84 | Dedicated File Name |
9F09 | Application Version Number |
9F34 | CVM Cardholder verification Method |
9F07 | Application Usage Control Indicates issuer‘s specified restrictions on the geographic usage and services allowed for the application |
9F0D | Issuer Action Code-Default |
9F0E | Issuer Action Code – Denial |
9F0F | Issuer Action Code – Online |
9F33 | Terminal Capabilities |
5F34 | Application PAN sequence Number |
9F39 | POS Entry Mode |
8E | CVM List Identifies a method of verification of the cardholder supported by the application |
5A | Application Primary Account Number |
57 | Track 2 equivalent |
5F20 OR 9F0B | Cardholder name or Extended |
9F1F | Track 2 discretionary data |
9F7A | VLP process indicator |
9F74 | VLP authorization code |
AuthorizeCard
Authorizes the EMV transaction amounts using the inserted chip (EMV) card after processing returns authorized card data in the form of tags.
Tags Returned from authorizeCard
Tag Identifier | Description |
---|---|
C2 | Signature Flag Authentication |
9B | Transaction Status Information |
9F27 | Cryptogram Information Data |
8A | Authorization response Code |
9F26 | Cryptogram returned by the ICC in response of the GENERATE AC command |
9F36 | Application Transaction Counter Counter maintained by the application in the ICC (incrementing the ATC is managed by the ICC) |
9F1 | Issuer Application Data |
ReadCardData
Reads the card data from the PAYMENT device and after processing returns the data in the TLV (Tag length Value) format*. *
Tags returned from ReadCardData
Tag Identifier | Description |
---|---|
4F | Application Identifier |
9F12 | Application preferred Name |
50 | Application Label |
5F30 | Service Code |
5F20 | Cardholder Name |
57 | Track 2 Equivalent Primary Account Number Field Separator (Hex 'D') Expiration Date (YYMM) Service Code Discretionary Data (defined by individual payment systems) Pad with one Hex 'F' if needed to ensure whole bytes |
5A | Application Primary Account Number |
5F24 | Application Expiry Date |
5F34 | Application Primary account Number sequence number |
5F25 | Application Effective Date |
For ReadMode.ALL mode, The D180 will fall back to swipe mode if the card inserted is not supported by payment device. Fallback to swipe is not supported for read modes like INSERT only and SWIPE only.
If encryption type RSA is set using setConfig API, ReadCardData with ReadMode.MANUAL mode returns the card data only if RSA Encryption key is injected into the D180.
completeOnLineEMV
Completes an online EMV transaction for PIN management.
Tags set through completeOnlineEMV
Tag Identifier | Description |
---|---|
91 | Issuer Authentication Data. Optional tag, if issuer authentication data is returned by host |
71/72 | Issuer Script. Optional tag, if issuer script is returned by host |
8A | Host Authorization Response Code |
89 | Host Authorization Code. Optional tag |
Behavior of EMDK Payment API when the PD40-100 displays Bluetooth connection status on its screen.
The user can use key combination specified in the PD40 manual to see the PD40 Bluetooth connection status. When this happens, PD40 shows the Bluetooth connection status on its displayed and while this status is displayed on the PD40 screen, calling payment API will result in communication error.
Behavior of re-enabling the PD40 immediately disabling
The application enables the PD40-100 and does the transaction, then disables the PD40-100. When applications requests EMDK to disable the connection with the PD40-100 by disable method, the disable method will be returned as soon it closes the Bluetooth socket connection. But Bluetooth stack is internally might take few seconds to free-up the resources associated with the established connection.
While this is happening, if the application tries to re-enable the payment device, it might lead to connection error.
To overcome this error, the application either wait for few seconds or register the BluetoothDevice.ACTION_ACL_DISCONNECTED intents or the EMDK PaymentManager connection listener to receive notification of the Bluetooth stack is successfully disconnected.
Choosing Payment Device:
This section describes how can the application access the payment device and enable it to do trasnaction.
Case 1: Payment Device Type supported (Such as PD40), choose payment device by friendly name.
List<DeviceInfo>; supportedList =
paymentManager.getSupportedDevicesInfo();
PaymentDevice device = null;
If(!supportedList.isEmpty()) {
device = paymentManager.getDevice(friendlyname,false);
device.enable();
} else {
//Error
}
Case 2: Multiple Payment Devices are paired and required payment device does not exist in the list.
List<DeviceInfo> pairedDevList =
paymentManager.getPairedDevicesInfo(DeviceType.PD40);
PaymentDevice device = null;
If(!pairedDevList.isEmpty()) {
//Traverse on the list of paired device and check if the required
device exists in the list.
If(required device not in the paired list) {
//Use scan and pair API to pair the device, or required device is not
already paired.
// device = paymentManager.getDevice(friendly name, false);
device = paymentManager.getDevice(macAddress, true);
device.enable();
}
}
Case 3: Multiple Payment Devices are paired and choose payment device from paired device list.
If the multiple payment devices are paired, the application can enumerate the list of paired devices and selects the required payment device. If the payment device is paired, but not in range or switched will result in the connection error during the enable.
List<DeviceInfo> pairedDevList =
paymentManager.getPairedDevicesInfo(DeviceType.PD40);
PaymentDevice device = null;
If(!pairedDevList.isEmpty()) {
device = paymentManager.getDevice((pairedDevList.get(1));
device.enable();
} else {
// No Payment devices paired
}
Case 4: Multiple Payment Devices are paired and chooses the default device. The default device is the device which is first available in the Bluetooth device paired list. If the device is paired, but not in range or switched-off, then it will give connection error.
PaymentDevice device =
paymentManager.getDevice(DeviceIdentifier.*DEFAULT*);
device.enable();
Case 5: Multiple Payment Devices are paired and chooses the first available PD40 device.
PaymentDevice device =
paymentManager.getDevice(DeviceIdentifier.PD40);
device.enable();
*Case 6: Multiple Payment Devices are paired and chooses the device using mac address or friendly name. *
PaymentDevice device = paymentManager.getDevice(“<mac
address>>”, true);
Or
PaymentDevice device = paymentManager.getDevice(“<friendly
name>>;”, false);
device.enable();
Case 6: Multiple payment devices are paired and set the mac address/friendly name via interface config
PaymentDevice device = paymentManager.getDevice(DEFAULT);
InterfaceConfig interfaceConfig = paymentDevice.getInterfaceConfig();
interfaceConfig.deviceName = "MPOS-64627969";
paymentDevice.setInterfaceConfig(interfaceConfig);
device.enable();
PD40 Remote Firmware and EMV Param Update
The Payment Manager is a service runs on mobile device which allows querying the information such as firmware/application version and current battery level; updating the firmware, updating EMV parameters and installing font on remote PD40 payment device. The updating EMV parameters and installing font will be supported in the future version. The PD40 payment devices must be paired with mobile device before using the Payment Manager.
The Payment Manager takes the input profile xml, performs the tasks specified in the input profile xml and returns response xml.
Communicating with Payment Service
The application must include the permission to access Payment Manager Service in application’s AndroidManifest.xml as below:
<uses-permission android:name="com.symbol.permission.PAYMENTMGR"/>;
The application must write a code start the Payment Manager Service and this can be achieved in two ways:
Binding Method
Intent Method
Binding Method
The Payment Manager Service exposes an AIDL (Android Interface Definition Language) for the application to communicate Payment Manager Service for querying and updating payment device.
The AIDL interface file name is “IPaymentManager.aidl” and its content is below:
package com.symbol.paymentmgr;
interface IPaymentManager {
String processXML(String profileXml);
}
The application can bind to Payment Manager Service and when the service is connected, the application can call the processXML method to perform the tasks specified the profile XML.
The Payment Manager Service package name and class details are below:
String PAYMENT_SERVICE_PACKAG_NAME = "com.symbol.paymentmgr";
String PAYMENT_SERVICE_CLASS_NAME =
"com.symbol.paymentmgr.PaymentMgrService";
Code snippet
Intent bindSvcIntent = new Intent();
bindSvcIntent.setComponent(new
ComponentName(PAYMENT_SERVICE_PACKAG_NAME,
PAYMENT_SERVICE_CLASS_NAME ));
bindService(bindSvcIntent, paymentMgrServiceConnObj,
Context.BIND_AUTO_CREATE);
IPaymentManager paymentMgr = null;
public class PaymentMgrServiceConn implements ServiceConnection {
@Override
public void onServiceConnected(ComponentName name, IBinder service) {
paymentMgr = IPaymentManager .Stub.asInterface(service);
String responseXml = paymentMgr. processXML(profileXml)
}
@Override
public void onServiceDisconnected(ComponentName name) {
}
}
unbindService(this);// Unbind service connection once at the end of
processing or application exit.
Intent Method
The Payment Manager Service exposes intent for the application to communicate Payment Manager Service for querying and updating payment device. The application must the send the profile XML as a part of the intent which starts the service and service will be exited automatically at the end of completion of the tasks specified in the profile.
Intents to start the payment service:
String PAYMENT_SERVICE_PACKAG_NAME = "com.symbol.paymentmgr";
String PAYMENT_SERVICE_CLASS_NAME =
"com.symbol.paymentmgr.PaymentMgrService";
String PAYMENT_SERVICE_PROFILE_EX_DATA_NAME =
"com.symbol.paymentmgr.PROFILE_XML”;
Intents to receive the result from the payment service:
String PAYMENT_SERVICE_RESULT_INTENT_NAME =
"com.symbol.paymentmgr.RESULT”;
String PAYMENT_SERVICE_ RESULT_EX_DATA_NAME =
"com.symbol.paymentmgr.RESPONSE”;
Code Snippet:
Start the Payment Service by sending intent to update the PD40 payment device.
Option 1:
Intent intent = new Intent();
intent.setAction(PAYMENT_SERVICE_PACKAG_NAME);
intent.putExtra(PAYMENT_SERVICE_PROFILE_EX_DATA_NAME,
profileXmlString);
startService(intent);
Option 2:
Intent intent = new Intent();
intent.setComponent(new
ComponentName(PAYMENT_SERVICE_PACKAG_NAME,
PAYMENT_SERVICE_CLASS_NAME ));
intent.putExtra(PAYMENT_SERVICE_PROFILE_EX_DATA_NAME,
profileXmlString);
startService(intent);
Register for the intent to receive result from the payment service:
IntentFilter filter = new IntentFilter();
filter.addAction(INTENT_PAYMNT_SERVICE_RESULT);
appContext.registerReceiver(broadcastReceiver, filter);
private final BroadcastReceiver broadcastReceiver = new
BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
if
(intent.getAction().equals(INTENT_PAYMNT_SERVICE_RESULT)) {
String responseString =
intent.getStringExtra(PAYMENT_SERVICE_ RESULT_EX_DATA_NAME);
}
}
};
//…
unregisterReceiver(broadcastReceiver); //Unregister the intent
receiver at the end.
Payment Manager Profile XML
The Payment Manager Profile allows the system admin application to query the payment device information such as firmware version and battery level, and update Payment Device. These capabilities are grouped together into single XML, what is referred to as Payment Manager Profiles.
Supported Parameters List
Parm Name | Description |
---|---|
DeviceAddress | List of PD40 Mac addresses or friendly names separated by “|”. If this value is empty or field doesn’t exists, all paired PD40 devices considered for query and update. Example: <parm name =“DeviceAddress” value=“11:22:33:44:55:66|MPOS-12345667”/> |
IsUpgradeOnly | The supported values are true/false. If this parameter is set to true, the downloading lower or same versions of firmware is not allowed. If this parameter is set to false, device will be updated independent of the version. The default value is true. This is an optional field, applicable only for firmware update and for others it will be ignored. Example: <parm name=“IsUpgradeOnly” value=“false”/> |
BatteryLevel | This queries the battery level of the PD40 Payment Device. This is optional field in the XML and is required only to query the PD40 battery level. Example: <parm-query name=“BatteryLevel”> Response: <parm name=“BatteryLevel” Value=“3”> The Battery level response values will be separated by | when queried for multiple devices. |
Version | This returns version of the PD40 firmware and application in the format “F<version>_A<version>”. This is required only to query the version. Example: <parm-query name=“Version”> Response: <parm name=“Version” Value=“F1.09_A1.2.0”> The versions will be separated by | for multiple devices. |
DownloadType | Download file types are “FIRMWARE”, “EMVPARAM” and “FONT”. This is mandatory to update the device. The EMVPARAM and FONT will be supported in the future version. Example: <parm name=“DownloadType” value=“FIRMWARE”/> |
DownloadFile | Name of the download file and its path. This is mandatory to update the device. The Firmware update file name format must be “D180_F<<version>_A<<version>>.bin or PD40_F<<version>_A<<version>>.bin Example: “D180_F1.07_A1.1.6.bin” The EMV Param update file name may look like emvpara or emvpara_<<n>> or any other name. Example: <parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.1.6.bin”/> <parm name=“DownloadFile” value=“/sdcard/emvpara”/> |
NumberOfRetries | Re-tries when connection failure or error occurs to update PD40 device. The default value is “1”. The range is 1 to 5. This is optional field in the XML. The Payment Manager will re-try after 500 ms if error any occurs and number of re-tries is greater than 1. Example: <parm name=“ NumberOfRetries” value=“2”/> |
MinPaymentDeviceBatteryLevel | Minimum Payment Device battery level to start the update process. If this field is not set, the payment device defined default value is used. This is optional field in the XML. Range is 0 to 4. Example: <parm name=“ MinPaymentDeviceBatteryLevel” value=“1”/> |
MinMobileDeviceBatteryLevel | Minimum Mobile Device battery level to start the update process. If this field is not set, 30% is considered as default. This is optional field in the XML. <parm name=“ MinMobileDeviceBatteryLevel” value=“40”/> |
Profile XML input
The profile must contain wap-provisioningdoc as root node, one or more characteristic node with type as PaymentMgr, version value as “0.1”. The version attribute is reserved for future use only. Each characteristic node can have one or more parm or parm-query nodes.
Example:
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<!—Sample characteristic node to update firmware -->
<characteristic type=“PaymentMgr” version="0.1" >
< parm name =“DeviceAddress”
value=“11:22:33:44:55:66|MPOS-12345667”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile”
value=“/sdcard/D180_F1.07_A1.1.6.bin”/>
</characteristic>
<!—Sample characteristic node to update firmware -->
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345001”/>
<parm name=“DownloadType” value=“ FIRMWARE”/>
<parm name=“DownloadFile”
value=“/sdcard/D180_F1.07_A1.1.6.bin”/>
</characteristic>
<!—Sample characteristic node to query version -->
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
<parm-query name =“Version”/>
</characteristic>
</wap-provisioningdoc>
Profile XML response
Success Case
The Payment Manager Service returns the xml same as the profile input or updated parm value(in case of query) if the request is processed successfully.
Failure Case
The corresponding characteristic node with failure will be renamed to characteristic-error, desc attribute will be added with the error details. If parm values specified are not valid, the corresponding parm node will be renamed to parm-error and desc attribute will be added with the error details.
If XML characteristic node has multiple devices requests, then desc will have error separated by | in the order of the devices list at the characteristic node desc filed.
Example:
If the input xml parm node has:
<parm name =“DeviceAddress” value=“11:22:33:44:55:66|00:00:00:00:99:11|MPOS-12345667”/>
The response xml characteristic node will be like:
characteristic-error type=“PaymentMgr” version="0.1"
desc=“REMOTE_DEVICE_NOT_PAIRED: Bluetooth remote device is not paired
with mobile device.|SUCCESS| REMOTE_DEVICE_BATTERY_LOW: Remote device
has low battery and operation can't be performed.”>
Not Supported Case
If any of the characteristic or parm node names specified is not valid or not supported, the desc attribute will be added with the feature not supported error information.
Example:
If the input xml parm node is:
<parm name="TimeZone1" value="GMT+05:30">
The response xml parm node will like:
<parm-error name="TimeZone1" value="GMT+05:30"
desc="FEATURE_NOT_SUPPORTED:The feature or parameters or its value is
not supported."/>
Example:
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<!—Firmware update response -->
<characteristic type=“PaymentMgr” version="0.1" >
< parm name =“DeviceAddress”
value=“11:22:33:44:55:66|MPOS-12345667”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile”
value=“/sdcard/D180_F1.07_A1.1.6.bin”/>
</characteristic>
<!— Firmware update response -->
<characteristic-error type=“PaymentMgr” version="0.1"
desc=”REMOTE_DEVICE_NOT_PAIRED:Bluetooth remote device is not
paired with mobile device.”>
< parm name =“DeviceAddress” value=“MPOS-12345001”/>
<parm name=“DownloadType” value=” FIRMWARE”/>
<parm name=“DownloadFile”
value=“/sdcard/D180_F1.07_A1.1.6.bin”/>
</characteristic>
<!—Version query response -->
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
< parm name =“Version” value=”F1.09_A1.2.0”/>
</characteristic>
</wap-provisioningdoc>
Error Codes
Error Name | Description |
---|---|
SUCCESS | Success |
FAILURE | Failure |
UNDEFINED | Unknown error occurred |
NULL_POINTER | Null pointer |
EMPTY_PROFILE_XML | Profile XML is empty |
INVALID_PROFILE_XML | The profile xml syntax is incorrect or not supported. |
INVALID_VALUE | Value is not valid. |
BUSY | Processing the other request. Try later... |
XML_SYNTAX_ERROR | XML syntax error |
FEATURE_NOT_SUPPORTED | The feature or parameters or its value is not supported. |
REMOTE_DEVICE_NOT_PAIRED | Bluetooth remote device is not paired with mobile device. |
FILE_NOT_EXISTS | The file specified in the profile xml does not exist. |
INITIALIZATION_ERROR | Error occurred during Initialization. |
UNINITIALIZATION_ERROR | Error occurred during un- Initialization. |
INVALID_FIRMWARE_FILE_NAME_FORMAT | The firmware file name format is invalid |
REMOTE_DEVICE_IN_USE | The remote device is used by other application. |
FAILED_ENABLE_REMOTE_DEVICE | Failed to open connection with remote device. |
FAILED_DISABLE_REMOTE_DEVICE | Failed to close connection with the remote device. |
FAILED_CONNECT_TO_REMOTE_DEVICE | Failed to establish Bluetooth connection with remote device. |
FIRMWARE_DOWNGRADE_NOT_ALLOWED | Downgrading the Firmware is not allowed. Set isUpgradeOnly=false in profile and try. |
REMOTE_DEVICE_BATTERY_LOW | Remote device has low battery and operation can't be performed. |
MOBILE_DEVICE_BATTERY_LOW | Mobile device battery level is low and operation can't be performed. |
REMOTE_DEVICE_DISCONNECTED | The remote device is got disconnected from mobile device. |
UPDATE_FILE_SIGNATURE_ERROR | The update file signature is not valid. |
REMOTE_DEVICE_TIME_OUT_ERROR | Remote device timed out during update process. Try again |
AUTHENTICATION_FAILED | Remote device failed to authenticate with mobile device. |
COMMUNICATION_ERROR | Error occurred during communication with the remote device. |
INCOMPLETE_UPDATE_FILE | The update file is incomplete or incorrect. |
UPDATE_FILE_TOO_LARGE | The update file passed is too large for remote device to update. |
DOWNLOAD_TIMEOUT | The download file request on payment device is timed out. |
BLUETOOTH_OFF | Bluetooth is OFF on host mobile device. |
FILE_VERIFICATION_FAILED | The download file format is not valid. |
Use Cases with Sample XML
This document lists XML format for only few use cases and it does not shows all the possible combinations.
Query PD40 Firmware/Application Version
The application should be able to query the payment device firmware/application versions.
Case 1: Query single payment device version
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
<parm-query name =“Version”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
<parm name =“Version” value=”F1.09_A1.2.0”/>
</characteristic>
</wap-provisioningdoc>
Case 2: Query multiple payment devices version
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress”
value=“MPOS-12345000|MPOS-123457865”/>
<parm-query name =“Version”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress”
value=“MPOS-12345000|MPOS-123457865”/>
<parm name =“Version” value=”F1.09_A1.2.0|F1.09_A1.1.9”/>
</characteristic>
</wap-provisioningdoc>
Case 3: Query all paired payment devices version
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm-query name =“Version”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress”
value=“MPOS-12345000|MPOS-123457865”/>
<parm name =“Version” value=”F1.09_A1.2.0|F1.09_A1.1.9”/>
</characteristic>
</wap-provisioningdoc>
Query PD40 Battery Level
The application should be able to query the payment device battery level.
Case 1: Query single payment device battery level
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
<parm-query name =“BatteryLevel”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
<parm name =“BatteryLevel” value=”2”/>
</characteristic>
</wap-provisioningdoc>
Case 2: Query multiple payment devices battery level
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress”
value=“MPOS-12345000|MPOS-123457865”/>
<parm-query name =“BatteryLevel”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name =“BatteryLevel” value=”1|4”/>
</characteristic>
</wap-provisioningdoc>
Case 3: Query all paired payment devices levels
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
< parm-query name =“BatteryLevel”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
< parm name =“ BatteryLevel” value=”1|4”/>
</characteristic>
</wap-provisioningdoc>
Updating PD40 Payment Device Firmware
The application should be able to update the payment device firmware.
Case 1: Updating single payment device firmware
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.0.bin”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.0.bin”/>
</characteristic>
</wap-provisioningdoc>
Case 2: Updating multiple payment devices with same firmware.
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile”
value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
</wap-provisioningdoc>
Case 3: Updating all paired payment devices with same firmware
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
</wap-provisioningdoc>
Case 4: Updating multiple payment devices with different firmware.
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.0.bin”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.0.bin”/>
</characteristic>
</wap-provisioningdoc>
Combination of Query and Firmware Update
Input XML
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress”
value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345002|MPOS-123457822”/>
<parm-query name =“Version”/>
</characteristic>
</wap-provisioningdoc>
Response XML (Success Case)
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345000|MPOS-123457865”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A1.2.1.bin”/>
</characteristic>
<characteristic type=“PaymentMgr” version="0.1" >
<parm name =“DeviceAddress” value=“MPOS-12345002|MPOS-123457822”/>
<parm name =“Version” value=”F1.09_A1.2.0| F1.09_A1.1.9”/>
</characteristic>
</wap-provisioningdoc>
Error Response XML Samples
Example 1:
The response for the profile input XML with
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<! --Success Node - ->
<characteristic type=“PaymentMgr” version="0.1" >
< parm name =“DeviceAddress” value=“11:22:33:44:55:66”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile”
value=“/sdcard/D180_F1.07_A1.1.6.bin”/>
</characteristic>
<! –Update failed Node - ->
<characteristic-error type=“PaymentMgr” version="0.1"
desc=“REMOTE_DEVICE_NOT_PAIRED:Bluetooth remote device is not
paired with mobile device.”>
< parm name =“DeviceAddress” value=“MPOS-12345678”/>
<parm name=“DownloadType” value=“FIRMWARE”/>
<parm name=“DownloadFile”
value=“/sdcard/D180_F1.07_A1.1.6.bin”/>
</characteristic-error>
<! –Invalid parameter Node ->
<characteristic-error type=“PaymentMgr” version="0.1” desc=“INVALID_VALUE: The download type is missing”>
< parm name =“DeviceAddress” value=“ MPOS-12345123”>
<parm -error name=“DownloadType” value=“” desc =“INVALID_VALUE:The download type is missing”/>
<parm name=“DownloadFile” value=“/sdcard/D180_F1.07_A10.5.0.bin”/>
</characteristic-error>
</wap-provisioningdoc>
Example 2:
The payment mgr response XML sample with two device successes and one device error for the version query.
<?xml version="1.0" encoding="utf-8"?>
<wap-provisioningdoc>
<! –Combination of success and error cases->
<characteristic-error type=“PaymentMgr” version="0.1"
desc=“SUCCESS|FAILED_CONNECT_TO_REMOTE_DEVICE:Failed to establish Bluetooth connection with remote device|SUCCESS”>
<parm name =“DeviceAddress” value=“MPOS-12345678|MPOS-12000002|MPOS-12300001”>
<parm name=“Version” value=“F1.07_A1.1.6||F1.07_A1.2.0/>
</characteristic-error>
</wap-provisioningdoc>