Miura Payloads
The Decryptx Payload Parser supports two Miura terminal models: 1) the M010 and 2) the Shuttle. Both devices/PEDs support magnetic stripe, keyed and EMV (chip&pin) input. The M010 also has a contactess reader. Both the M010 and Shuttle have Bluetooth, USB and TCP/IP interfaces; they are designed to operate as counter-top and as mobile devices. Mobile devices will typically use the Bluetooth interface, whereas Point of Sale (POS) applications will use the serial USB or TCP/IP over WIFI interfaces. While the PEDs support multiple interfaces the commands sent and responses received from them are the same no matter which interface is used.
The terminal vendor supplies software development kits for a wide variety of operating systems and development languages on their developer's portal. They make it easy for the POS application or mobile device to obtain data for the payment terminal. In this guide we include sample code that use Miura's Android SDK to extract a P2PE secured payload from an RBA terminal. Miura provide similar SDKs in Python, Objective-C, and a number of other languages. While the programming languages are different, the software use a similar pattern when extracting the encrypted data from the terminal.
Raw commands and SDKs
As mentioned above the Miura PEDs are designed to work over Bluetooth and USB. These interfaces consume command strings and produce response strings in an asynchronous fashion. As with most devices that utilize a Bluetooth interface, keeping these command strings compact is a high priority; they use a single byte to represent a command and as little bytes as possible. For example the following command 010004D0020000D4 has a prologue of 010004 and an LRC at end of D4; the actual command of D0020000 requests the device information. See the Miura MPI API documentation for the full description of these commands. Thankfully, Miura has a number of SDKs that abstract away these command strings. The following example retrieves the same information (note the listener class that waits for the async response).
MiuraManager.getInstance().getSoftwareInfo(new ApiGetSoftwareInfoListener() {
@Override
public void onSuccess(SoftwareInfo softwareInfo) {
//information can be accessed here.
}
@Override
public void onError() {
System.out.println( "Error occurred" );
}
});Identifying the serial number
The device's serial number is a required parameter when calling the decrypt endpoint. A version of the serial number is usually printed on the back of the device. The printed value typically has a dash, e.g: 010-589951, however the API expects that the serial value drop the dash and leading zero to e.g. 10589951. The serial number can also be identified by sending a GET DEVICE INFO command to the PED. The raw command is 010004D0020000D4 and the Android SDK command is:
MiuraManager.getInstance().getSoftwareInfo(new ApiGetSoftwareInfoListener() {
@Override
public void onSuccess(SoftwareInfo softwareInfo) {
System.out.println( "Serial Number" + softwareInfo.getSerialNumber() );
}
@Override
public void onError() {
System.out.println( "Error occurred" );
}
});Once you have the serial numbers you need to extract the payload and KSN. Typically when capturing a payload, text should be displayed to the user prompting them to insert their card or swipe. You can use the MiuraManager.getInstance().displayText method. For brevity we have omitted text prompts from the samples below, the Miura documentation has a section outlining the appropriate payment data capture flow and text to display at each step during that flow. By default all the readers (mag stripe, chip, and contactless) are disabled on the PED. You need to send a command to activate them as follows:
Magnetic Stripe
To capture a magnetic strip payload we need to send the CARD STATUS command. The card status command is used to query if a card is in the EMV slot and to enable capture of magnetic stripe data. It is also used to enable or disable unsolicited card status change messages from the PED. In the following Android code we attach our connectionDelegate which listens for card status changes and we set the CARD STATUS to true.
MiuraManager.getInstance().setConnectionDelegate(connectionDelegate);
MiuraManager.getInstance().cardStatus(true, null);The following is an example of our connectionDelegate that listens for a card swipe. The delegate can be attached to a number of other SDK methods, when capturing a swiped transaction we are only interested in the onCardStatusChange method. Then when a card is swiped or inserted into the EMV slot, a CardData object is passed into the onCardStatusChange method. This object has methods to detect if the event was triggered by one or the other; see the EMV section for details. In our example we check that the card data object has track2 data. If it does then we know it is a magnetic stripe payload and it will contain SRED and KSN data.
private MPIConnectionDelegate connectionDelegate = new MPIConnectionDelegate() {
@Override
public void connected() {}
@Override
public void disconnected() {}
@Override
public void connectionState(boolean flg) {}
@Override
public void onKeyPressed(int keyCode) {}
@Override
public void onCardStatusChange( CardData cardData ) {
if ( cardData.getTrack2Data() != null ) {
final String payload = cardData.getSredData();
final String ksn = cardData.getSredKSN();
//send P2PE data to backend server to process.
}
}
@Override
public void onDeviceStatusChange(DeviceStatus deviceStatus, String statusText) {}
@Override
public void onBatteryStatusChange(BatteryData batteryData) {}
@Override
public void onBarcodeScan(String scanned) {}
@Override
public void onPrintSledStatus(M012Printer m012PrinterStatus) {}
}Sample magnetic strip payload:
0e64f89987343361346fcb63419cadb9733be3d555c4024294d1ec7c9fc6997010313c15212628348b22f0cec67ab5d5c7ee63c01dd28644aad4ba94223dc224089a142d5db1a3adf7803b3396269154a5584b8c61bbffa7f382ff713e28d3cdSample KSN:
fffff001030000200001Sample cURL request with magnetic swipe payload and KSN.
curl 'https://cert-parser.decryptx.com/api/v1/decrypt/parser' \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
-d '{
"partnerId" : "WATERFORD",
"partnerKey" : "ef1ad938150fb15a1384b883a104ce70",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"ksn" : "fffff001030000200001",
"deviceType" : "miura",
"deviceSerial" : "10589951",
"devicePayload" : "0e64f89987343361346fcb63419cadb9733be3d555c4024294d1ec7c9fc6997010313c15212628348b22f0cec67ab5d5c7ee63c01dd28644aad4ba94223dc224089a142d5db1a3adf7803b3396269154a5584b8c61bbffa7f382ff713e28d3cd"
}'Response body from the cURL request:
{
"success" : true,
"messageId" : "1201706151533581022507812",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"meta" : {
"device" : "MIURA",
"serial" : "10589951",
"mode" : "swiped"
},
"track1" : {
"decrypted" : "2542343132343933393939393939393939305e544553542f424c554546494e5e323231323130313132333435363738393f5f",
"encoding" : "hex",
"length" : 50,
"ascii" : "%B4124939999999990^TEST/BLUEFIN^2212101123456789?_",
"masked" : "%*412493******9990^TEST/BLUEFIN^2212*********?*"
},
"track2" : {
"decrypted" : "3b343132343933393939393939393939303d323231323130313132333435363738393f3b",
"encoding" : "hex",
"length" : 36,
"ascii" : ";4124939999999990=2212101123456789?;",
"masked" : ";412493******9990=2212************?*"
},
"extracted" : {
"PAN" : "4124939999999990",
"EXPY" : "1222",
"Surname" : "TEST",
"FirstName" : "BLUEFIN",
"ServiceCode": "101",
"Discretionary": "123456789"
}
}
The response from a swiped payload will contain track1 and track2 data. The extracted object will contain PAN, EXPY, Surname and FirstName data.
EMV (Chip & Pin)
To capture an EMV payload we start by sending the same CARD STATUS command to the PED. When the CardData object is passed to the onCardStatusChange method of the MPIConnectionDelegate it will have a number of properties that will inform us if the card is EMV enabled cardData.getCardStatus().isEMVCompatible() and in the chip reader slot cardData.getCardStatus().isCardPresent(). If both of these are true then we initiate an EMV transaction with the START TRANSACTION command.
The following sample code initiates an EMV transaction; specified in the command call is the transaction type, the transaction amount amd the currency code. Attached to the command is an ApiStartTransactionListener with code that is executed once the application receives data from the contactless transaction. Included in this data is the encrypted payload and the KSN. Also included in the data is issuer/acquirer data which can be checked before a CONTINUE TRANSACTION command is sent.
MiuraManager.getInstance().setConnectionDelegate(connectionDelegate);
MiuraManager.getInstance().cardStatus(true, null);
private MPIConnectionDelegate connectionDelegate = new MPIConnectionDelegate() {
@Override
public void connected() {}
@Override
public void disconnected() {}
@Override
public void connectionState(boolean flg) {}
@Override
public void onKeyPressed(int keyCode) {}
@Override
public void onCardStatusChange( CardData cardData ) {
if (cardData.getCardStatus().isCardPresent() && cardData.getCardStatus().isEMVCompatible()) {
MiuraManager.getInstance().startTransaction(TransactionType.Purchase, transactionInfo.getAmount(), MiuraApplication.currencyCode.getValue(), new ApiStartTransactionListener() {
@Override
public void onSuccess(byte[] result) {
List<TLVObject> tlvObjects = TLVParser.decode(result);
final TLVObject payloadObj = CommandUtil.firstMatch( tlvObjects, Description.SRED_Data );
final TLVObject ksnObj = CommandUtil.firstMatch( tlvObjects, Description.SRED_KSN );
final String payload = payloadObj.getData();
final String ksn = ksnObj.getData();
//the tlvObject contains other issuer data. That data should be presented
//to the user before the continueTransaction command is executed. The response
//to the continue command will also contain the payload and ksn data.
}
@Override
public void onError(TransactionResponse response) {
}
});
}
}
@Override
public void onDeviceStatusChange(DeviceStatus deviceStatus, String statusText) {}
@Override
public void onBatteryStatusChange(BatteryData batteryData) {}
@Override
public void onBarcodeScan(String scanned) {}
@Override
public void onPrintSledStatus(M012Printer m012PrinterStatus) {}
}Sample EMV payload:
cdeb04ca81940babb24acf4ffa9d6b77fb52c6bc0890edbcfc518c7b724d1be1Sample KSN:
fffff00103000020001bSample cURL request with EMV payload and KSN:
curl 'https://cert-parser.decryptx.com/api/v1/decrypt/parser' \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
-d '{
"partnerId" : "WATERFORD",
"partnerKey" : "ef1ad938150fb15a1384b883a104ce70",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"ksn" : "fffff00103000020001b",
"deviceType" : "miura",
"deviceSerial" : "10589951",
"devicePayload" : "cdeb04ca81940babb24acf4ffa9d6b77fb52c6bc0890edbcfc518c7b724d1be1"
}'Response body from the cURL request:
{
"success" : true,
"messageId" : "1201706160927451032904876",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"meta": {
"device" : "MIURA",
"serial" : "10589951",
"mode" : "emv"
},
"track2equivalent": {
"decrypted" : "4761739001010119d22122011143804400000",
"encoding" : "ascii",
"length" : 37,
"ascii" : "4761739001010119d22122011143804400000",
"masked" : "476173******0119d2212****************"
},
"track2": {
"decrypted" : ";4761739001010119=22122011143804400000?",
"encoding" : "ascii",
"length" : 39,
"ascii" : ";4761739001010119=22122011143804400000?",
"masked" : ";476173******0119=2212****************?"
},
"extracted": {
"PAN" : "4761739001010119",
"EXPY" : "1222",
"ServiceCode" : "201",
"Discretionary" : "1143804400000"
}
}The response from an EMV payload will contain a track2equivalent object. This object will contain EMV TAG 57 data. We also create a track2 object based on the contents of the track2equivalent object. The track2 data follows the standard track2 swipe format. The extracted object will contain PAN and EXPY data.
Contactless
As the form factor of the M010 PED is quite compact it is possible that it would accidental read a contactless payload when a user attempts to swipe their card. Therefore the PED's contactless reader is not enabled by default. A START CONTACTLESS TRANSACTION command that must be sent to the PED.
The following sample code initiates a contactless transaction; specified in the command call is the transaction type, the transaction amount and the currency code. Attached to the command is an ApiStartTransactionListener with code that is executed once the application receives data from the contactless transaction. Included in this data is the encrypted payload and the KSN.
MiuraManager.getInstance().startContactlessTransaction(TransactionType.Purchase, transactionInfo.getAmount(),
MiuraApplication.currencyCode.getValue(), new ApiStartTransactionListener() {
@Override
public void onSuccess(byte[] result) {
List<TLVObject> tlvObjects = TLVParser.decode(result);
final TLVObject payloadObj = CommandUtil.firstMatch( tlvObjects, Description.SRED_Data );
final TLVObject ksnObj = CommandUtil.firstMatch( tlvObjects, Description.SRED_KSN );
final String payload = payloadObj.getData();
final String ksn = ksnObj.getData();
//the tlvObject contains other issuer data. That data should be presented
//to the user before the continueContactlessTransaction command is executed.
//The response to the continue command will also contain the payload and ksn data.
}
@Override
public void onError(TransactionResponse response) {
}
});Sample contactless payload:
c31b8d370f9edc2d6bc2af63d49f9b37372a481653d1df25Sample KSN:
fffff00103000020004dSample cURL request with contactless payload and KSN.
curl 'https://cert-parser.decryptx.com/api/v1/decrypt/parser' \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
-d '{
"partnerId" : "WATERFORD",
"partnerKey" : "ef1ad938150fb15a1384b883a104ce70",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"ksn" : "fffff00103000020004d",
"deviceType" : "miura",
"deviceSerial" : "10589951",
"devicePayload" : "c31b8d370f9edc2d6bc2af63d49f9b37372a481653d1df25"
}'Response body from the cURL request:
{
"success" : true,
"messageId" : "1201706160934521032652372",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"meta" : {
"device" : "MIURA",
"serial" : "10589951",
"mode" : "emv"
},
"track2equivalent": {
"decrypted" : "4761739001010119d22122011143804400000",
"encoding" : "ascii",
"length" : 37,
"ascii" : "4761739001010119d22122011143804400000",
"masked" : "476173******0119d2212****************"
},
"track2": {
"decrypted" : ";4761739001010119=22122011143804400000?",
"encoding" : "ascii",
"length" : 39,
"ascii" : ";4761739001010119=22122011143804400000?",
"masked" : ";476173******0119=2212****************?"
},
"extracted": {
"PAN" : "4761739001010119",
"EXPY" : "1222",
"ServiceCode" : "201",
"Discretionary" : "1143804400000"
}
}The response from an contactless payload is the same as an EMV payload. The track2equivalent object will contain EMV TAG 57 data. We also create a track2 object based on the contents of the track2equivalent object. The track2 data follows the standard track2 swipe format. The extracted object will contain PAN and EXPY data.
Keyed
To capture keyed card data the command GET SECURE PAN must be sent to the device. A prompt is displayed on the device to enter card data. Once the user presses the enter key the encrypted payload and KSN data is returned. The encrypted payload contains the PAN data only; expiry date and/or CVV must be retrieved separately via GET TEXT command.
Unfortunately the MiuraManager class doesn't have a method in it to initiate a keyed payload capture, therefore we have to use the low level MPICommandCreator class. The command string to request the PAN is as follows: 01000FD25A00010AE008DFA2060400000001 where 01000F is the prologue, D25A is the command request a secure PAN, 0001 configures the backlight (0001 is on; 0000 is off) and 0AE008DFA2060400000001 specifies the index of the prompt text. MPICommandCreator looks after the prologue, we specify the command type, the config options and the data field.
BaseBluetooth.getInstance().setDelegate(connectionDelegate, commandDelegate);
final byte[] dataField = BinaryUtil.parseHexBinary( "E008DFA2060400000001" );
final byte[] command = MPICommandCreator.createCommand(InterfaceType.MPI, MPICommandCreator.CommandType.Get_Secure_PAN, (byte) 0, (byte) 1, dataField);
BluetoothService.getInstance().write(command);
return command;In the code above we set a command delegate on the BaseBluetooth object that listens for the message containing the decrypted PAN data. The following sample MPICommandDelegate extracts the encrypted payload and KSN from the message.
final MPICommandDelegate commandDelegate = new MPICommandDelegate() {
@Override
public void receivedSolicitedMessage( ResponseMessage responseMessage ) {
if( responseMessage.isSuccess() && responseMessage.getBody().length > 1) {
final List<TLVObject> tlvObjects = TLVParser.decode(responseMessage.getBody());
final TLVObject payloadObj = CommandUtil.firstMatch( tlvObjects, Description.SRED_Data );
final TLVObject ksnObj = CommandUtil.firstMatch( tlvObjects, Description.SRED_KSN );
final String payload = payloadObj.getData();
final String ksn = ksnObj.getData();
//send P2PE data to backend server to process.
}
}
});Sample keyed payload:
bec06a99af283f8541875de76d05ed8676aef285646ee758Sample KSN:
fffff00103000020004fSample cURL request with keyed payload and KSN.
curl 'https://cert-parser.decryptx.com/api/v1/decrypt/parser' \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
-d '{
"partnerId" : "WATERFORD",
"partnerKey" : "ef1ad938150fb15a1384b883a104ce70",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"ksn" : "fffff00103000020004f",
"deviceType" : "miura",
"deviceSerial" : "10589951",
"devicePayload" : "bec06a99af283f8541875de76d05ed8676aef285646ee758"
}'Response body from the cURL request:
{
"success" : true,
"messageId" : "1201706160843391032761684",
"reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
"meta" : {
"device" : "MIURA",
"serial" : "10589951",
"mode" : "keyed"
},
"keyed" : {
"decrypted" : "103630313130313333333333333333333100000000",
"encoding" : "hex",
"length" : 16,
"ascii" : "6011013333333331",
"masked" : "601101******3331"
},
"extracted" : {
"PAN" : "6011013333333331"
}
}The response from a keyed payload will contain a keyed object. This keyed ascii value will simply be the PAN as that is all that is included in the encrypted payload. The extracted object will only contain the PAN.