Magtek IPAD, Programmer'S Reference Manual

Page 1: ...Phone 562 546 6400 I Technical Support 888 624 8350 www magtek com IPAD DynaPro DynaPro Go and DynaPro Mini PIN Encryption Devices Programmer s Reference Microsoft Windows Store March 2017 Manual Par...

Page 2: ...MagTek Inc MagTek is a registered trademark of MagTek Inc DynaPro DynaPro Go DynaPro Mini and IPAD are trademarks of MagTek Inc Bluetooth is a registered trademark of Bluetooth SIG Oracle and Java are...

Page 3: ...nder this Agreement are automatically terminated COPYRIGHT The Software is copyrighted Licensee may not copy the Software except for archival purposes or to load for execution purposes All other copie...

Page 4: ...ornia and shall inure to the benefit of MagTek Incorporated its successors or assigns ACKNOWLEDGMENT LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT UNDERSTANDS ALL OF ITS TERMS CONDITIONS AND R...

Page 5: ...in Windows Store 12 3 MTPPSCRAPCL Functions 13 3 1 getSDKVersion 13 3 2 openDevice 13 3 3 closeDevice 13 3 4 getDeviceList 14 3 5 isDeviceOpened 14 3 6 deviceReset 14 3 7 getStatusCode 14 3 8 cancelOp...

Page 6: ...a 26 3 36 requestUserDataEntry 27 3 37 requestResponse 28 3 38 confirmAmount 29 3 39 selectCreditDebit 29 3 40 requestPIN 29 3 41 requestSignature 31 3 42 requestSmartCard 31 3 43 sendAcquirerResponse...

Page 7: ...PublicKeySync 54 4 MTPPSCRAPCL Delegate 56 4 1 OnErrorEvent 56 4 2 OnDataReadyCompleteEvent 56 4 3 OnPowerUpICCCompleteEvent 56 4 4 OnAPDUArrivedCompleteEvent 56 4 5 OnGetCAPublicKeyCompleteEvent 57 4...

Page 8: ...CBC to decrypt track data 65 C 3 Calculate CBC MAC 66 C 3 1 Get key 66 C 3 2 Padding data 66 C 3 3 Calculate MAC by CBC 66 C 4 Cryptography in CA Public Key EMV Tag and EMV transaction 66 C 4 1 Send...

Page 9: ...0 Table of Contents IPAD DynaPro DynaPro Go and DynaPro Mini PIN Encryption Devices Programmer s Reference Microsoft Windows Store Page 9...

Page 10: ...d internally as part of an enterprise solution 1 2 Nomenclature The general terms device and host are used in different often incompatible ways in a multitude of specifications and contexts For exampl...

Page 11: ...Mini PIN Encryption Devices Programmer s Reference Microsoft Windows Store Page 11 File name Description MTPPService dll DLL required to interact with the PIN Encryption Device 1 4 System Requirement...

Page 12: ...Build MTPPSCRACSDemo WSDesktop To Run Debug the MTPPSCRADemo WSDesktop software follow these steps 1 Select Build Configuration equal to Debug and Build platform to AnyCPU 2 In VisualStudio select Deb...

Page 13: ...from the user will run in the asynchronous mode 3 1 getSDKVersion This function retrieves the library version information String getSDKVersion Return Value String containing the Version of the Java li...

Page 14: ...connected to the device otherwise False 3 6 deviceReset This function sends a reset command to the device int deviceReset Return Value Returns a value 0 Success Non Zero Error 3 7 getStatusCode This...

Page 15: ...String lpAmount ref int opStatus Parameter Description amountType RFU lpAmount Amount to be used for the transaction should be a null terminated string For example 20 56 opStatus An integer pointer to...

Page 16: ...the challenge key and session key for a smart card transaction For additional information see Appendix B EMV CBC MAC byte requestChallengeAndSession Return Value A byte array containing the challenge...

Page 17: ...e device int endL1Session ref int opStatus Parameter Description opStatus An integer pointer to receive the command response or operation status Zero value means OK For more values see Appendix A Retu...

Page 18: ...ccess Non Zero Error 3 19 sendSpecialCommand This function sends a direct SET byte command to the device For information about direct commands see 99875585 DynaPro Programmer s Reference Commands and...

Page 19: ...e reserved Parameter Description tagType EMV tag to set or get 0x00 Reader tags 0x80 Application tags Lower 7 bits indicate which application slot of operation operation Type of operation to be perfor...

Page 20: ...ch application slot of operation operation Type of operation to be performed 4 Write EMV Reader tags 5 Write EMV Application tags 0xFF Set to factory defaults inputTLVData TLV data block to send to th...

Page 21: ...d message or bitmap on the device s LCD display The event associated with this function is OnDisplayRequestComplete int setDisplayMessage int waitTime int messageID ref int opStatus Parameter Descript...

Page 22: ...er is 0 clear the current image will be cleared from the specified slot Otherwise if the command is successful the new bitmap image data will be stored in the specified slot with the selected format a...

Page 23: ...scription mode ID for information the device should return 0 Product_ID 1 Maximum Application Message Size 2 Capability String 3 Manufacturer 4 Product Name 5 Serial Number 6 Firmware Number 7 Build I...

Page 24: ...questKernelInformation This function retrieves the device s kernel information int requestKernelInformation int kernelInfoID byte kernelInfoBuffer Parameter Description kernelInfoID Key information ID...

Page 25: ...N value It requires that the software first call requestPIN or requestCard for valid KSN data This feature is used for the Token Reversal Function and not supported on DynaPro Go String getKSN Return...

Page 26: ...ain beepTones Tone to use 0x00 No Sound 0x01 Single Beep 0x02 Double Beeps lpFieldSep Delimiter to separate the output data Return Value Returns a value 0 Success Non Zero Error 3 35 requestManualCard...

Page 27: ...pointer to receive the command response or operation status Zero value means OK For more values see Appendix A Return Value Returns a value 0 Success Non Zero Error 3 36 requestUserDataEntry This fun...

Page 28: ...The device will prompt the user to select a transaction type or user defined message The event associated with this function is OnKeyInput int requestResponse int waitTime int selectMsg int keyMask in...

Page 29: ...3 39 selectCreditDebit This function prompts the user to confirm the card type The event associated with this function is OnKeyInput int selectCreditDebit int waitTime int beepTones Parameter Descript...

Page 30: ...n PIN entry pinMode Message to display as a user prompt 0 PINsgEnterPIN 1 PINMsgEnterPINAmt 2 PINMsgReenterPINAmt 3 PINMsgReenterPIN 4 PINMsgVerifyPIN maxPINLength Minimum PIN length Must be greater t...

Page 31: ...ses the CANCEL button If there are no errors the device will prompt the user to approve an amount and swipe or insert card by displaying pre determined EMV messages The LCD display will cycle showing...

Page 32: ...stage The device can be directed to allow PIN bypass using requestBypassPINCommand The PIN requirement can also be bypassed by the cardholder The transaction approval method will be determined per EM...

Page 33: ...beepTones Tone to use 0 None 1 Single Beep 2 Double Beep option Transaction options 0 Normal 1 Bypass PIN 2 Force Online 4 Acquirer not available amount The amount to be used and authorized EMV Tag 9F...

Page 34: ...ncMPLength public byte EncMPStatus public byte EncTrack1Length public byte EncTrack1Status public byte EncTrack2Length public byte EncTrack2Status public byte EncTrack3Length public byte EncTrack3Stat...

Page 35: ...ration status Zero value means OK For more values see Appendix A Return Value Returns the current device configuration which is an array of bytes 3 46 getProductID This function returns the device s p...

Page 36: ...is attached to a computer 0 if the device is not attached to computer 3 53 getSessionState This function gets the device session state The value is valid after calling requestDeviceStatus int getSess...

Page 37: ...atus Parameter Description firmwareData Binary data of firmware opStatus An integer value to receive the command response or operation status Zero value means OK For more values see Appendix A Return...

Page 38: ...e the secured RAPDU pdwDataLen Size of buffer opStatus An integer pointer to receive the command response or operation status Zero value means OK For more values see Appendix A Return Value Returns a...

Page 39: ...e report to the device The device will prompt the user to select a transaction type or user defined message User response will be returned in the key variable int requestResponseSync int waitTime int...

Page 40: ...nc int waitTime int tones ref byte key ref int opStatus Parameter Description waitTime Time the device will wait for the user to confirm the amount beepTones Tone to use 0 None 1 Single Beep 2 Double...

Page 41: ...value 0 Success Non Zero Error 3 62 requestPINSync This function wraps device command 0x04 It directs the device to prompt the user to enter a PIN by displaying one of five predetermined messages and...

Page 42: ...IN 3 ISO3 Format Verify PIN pin A PIN_DATA structure to hold the user PIN public struct PIN_DATA public byte OpStatus public string KSN public string EPB KSN PIN KSN EPB Encrypted PIN Block in ISO for...

Page 43: ...Prompts Figure 3 10 DynaPro Mini Initial Swipe Prompt Parameter Description waitTime Time the device will wait for the user to complete a card swipe messageID Message to prompt the user with 0x00 Car...

Page 44: ...yte MSStatus public byte PANInfoLength public uint reserved public byte Track1Length public byte Track1Status public byte Track2Length public byte Track2Status public byte Track3Length public byte Tra...

Page 45: ...ransaction Card data will be returned in CARD_DATA structure int requestManualCardDataSync int waitTime int beepTones int options ref CARD_DATA card ref int opStatus Parameter Description waitTime Tim...

Page 46: ...yte MSStatus public byte PANInfoLength public uint reserved public byte Track1Length public byte Track1Status public byte Track2Length public byte Track2Status public byte Track3Length public byte Tra...

Page 47: ..._DATA structure int requestUserDataEntrySync int waitTime int displayMessageID int beepTones ref USER_ENTRY_DATA userData ref int opStatus Parameter Description waitTime Time the device will wait for...

Page 48: ...serData ref int opStatus Parameter Description waitTime Time the device will wait for the user to begin data entry displayMessageID Message to prompt the user with 0 SSN 1 Zip code 2 Birth four digit...

Page 49: ...lation button If the cardholder presses the confirmation button then depending on the card type requested to be read the LCD display will show either SWIPE or INSERT CARD If the user presses the cance...

Page 50: ...s to the host using OnEMVDataCompleteEvent for approval starts a HOST response timer and waits for SendAcquirerResponse from the host processes the Host Response gets TC or AAC from the ICC depending...

Page 51: ...used EMV Tag 9F02 format n12 It should be a 6 byte array reserved 29 byte array reserved for future use arqcTag If operation is successfully ARQC will returned in ACQUIRER_DATA structure Otherwise ba...

Page 52: ...sSync This function sends the EMV Tag report to the device to read or write EMV Tags For additional information see Appendix B EMV CBC MAC int requestGetEMVTagsSync int tagType int tagOperation byte i...

Page 53: ...a value 0 Success Non Zero Error 3 71 requestSetEMVTagsSync This function sends the EMV Tag report to the device to read or write EMV Tags For additional information see Appendix B EMV CBC MAC int req...

Page 54: ...s deletes the corresponding CA Public Key depending on the operation specified For additional information see Appendix B EMV CBC MAC int setCAPublicKeySync int operation byte keyBlock int keyBlockLeng...

Page 55: ...3 MTPPSCRAPCL Functions IPAD DynaPro DynaPro Go and DynaPro Mini PIN Encryption Devices Programmer s Reference Microsoft Windows Store Page 55 Return Value Returns a value 0 Success Non Zero Error...

Page 56: ...PPSCRADemo WSDesktop in the SDK files 4 1 OnErrorEvent public delegate void OnErrorEvent int errorCode Parameter Description errorCode An integer error code for an error handler 4 2 OnDataReadyComplet...

Page 57: ...both versions of onPINRequestComplete Developers may choose to use this form which receives the return data as a string or the other form which receives the return data as a structure public delegate...

Page 58: ...parse the array into a structure public delegate void OnCardRequestCompleteEvent String lpData Parameter Description lpData A response string for the requestCard function 4 12 OnUserDataEntryCompleteE...

Page 59: ...escription stateId EMV cardholder interaction ID 0x01 Waiting for amount confirmation selection 0x02 Amount confirmation selected 0x03 Waiting for multi payment application selection 0x04 Application...

Page 60: ...g ToString 4 18 OnProgressUpdateEvent Progress update event for SendBitmap and UpdateFirmware public delegate void OnProgressUpdateEvent byte opStatus int UpdateItem double updateProgress Parameter De...

Page 61: ...vices Programmer s Reference Microsoft Windows Store Page 61 Parameter Description state Disconnected device removed or closed Connecting device is in the open progress Error device is in error state...

Page 62: ...ER_SIZE 0x0E UNSUPPORT_FUNCTION 0x0F BUSY 0x10 CORRECT_DATA_NOT_EXIST 0xFF UNKNOWN_ERROR A 2 Operation Status Codes 0x00 OK Done 0x01 User Cancel 0x02 Timeout 0x03 Host Cancel 0x04 Verify fail 0x05 Ke...

Page 63: ...RL 0x92 Invalid Cert CRL Message 0x93 Revoked Cert CRL 0x94 CRL non exist 0x95 Cert exists 0x96 Duplicate KSN Key Appendix B EMV CBC MAC For additional information about EMV related functions for use...

Page 64: ...ta EPB Then derive key from BDK and KSN byte bPinKey To get the bPinKey reference to ANSI X9 24 C 1 2 Use Triple DES CBC to decrypt PIN block Decrypt Encrypted PIN Block use empty initial vector byte...

Page 65: ...ialNumber public byte PANInfoLength public string PANInfo public UInt32 reserved C 2 1 Get Track binary from CARD_DATA First convert EncTrack1 EncTrack2 EncTrack3 and KSN from hex string to byte array...

Page 66: ...3 Calculate MAC by CBC Use DES CBC to encrypt data then use DES DECB and DES ECB to encrypt last block as MAC Then the most left 32 bits as MAC value byte pLeftKey new byte 8 byte pRightKey new byte 8...

Page 67: ...stSmartCard Following sample code demonstrate an EMV transaction flow C 5 1 Host RequestSmartCard byte Amt new byte 6 0x0 0x0 0x0 0x01 0x0 0x0 byte Cashback new byte 6 0x0 0x0 0x0 0x0 0x0 0x0 int retC...

Page 68: ...26 byte 0xDF Msg 27 0x25 Msg 28 0x08 Array Copy SerialNumber 0 Msg 29 8 Set Data Msg 37 0xFA Msg 38 0x82 Msg 39 0 Msg 40 6 Array Copy approve 0 Msg 41 6 byte OutputMsg int OutputMsgLen Use CBC MAC to...

Page 69: ...ge 5 Using requestConfirmSession to create communicate session predefined key deriving mask byte amkDerivedSessionCMAC_Mask 0x5e 0x55 0x00 0xb7 0x89 0xc4 0x76 0xf3 0x6d 0xac 0xdc 0x90 0x13 0x2a 0xbd 0...

Page 70: ...s new byte 8 TDES_Encrypt_CBC bAMKSessionKey iv transformedNumberSerial 8 trns 8 Calculate CMAC byte cmac new byte 8 CMAC bAMKCMACKey trns 8 cmac 8 byte ernd SubArray trns 0 4 byte eserial SubArray tr...

Page 71: ...y TDES_Encrypt_CBC SessionKey iv Apdu ApduLength EncApduBuffer EncApduBufferLen Generate CMAC for this APDU byte cmac 8 new byte 8 CMAC SessionCMACKey iv EncApduBuffer EncApduBufferLen cmac 8 Append c...

Page 72: ...S YES setPAN YES YES YES YES setAmount YES YES YES YES endSession YES YES YES YES requestChallengeAndSessionForInformation NO YES YES YES requestConfirmSession NO YES YES YES endL1Session NO YES YES Y...

Page 73: ...ES YES YES YES requestSignature YES YES NO RF requestSmartCard NO YES YES YES sendAcquirerResponse NO YES YES YES getCardDataInfo YES YES YES YES requestDeviceConfiguration YES YES YES YES getProductI...

Page 74: ...eters YES YES YES YES getParameters YES YES YES YES getEPB YES YES YES YES clearBuffer YES YES YES YES requestClearTextUserDataEntry NO NO NO YES requestClearTextUserDataEntrySync NO NO NO YES request...

Page 75: ...RF onCardRequestComplete YES YES YES YES onUserDataEntry YES YES YES YES onDeviceStateUpdated YES YES YES YES onEMVDataComplete NO YES YES YES onCardHolderStateChanged NO YES YES YES onEMVTransactionC...