Magensa Qwickpin, Generation/Verification of PIN Offset
Total Page:16
File Type:pdf, Size:1020Kb
Magensa QwickPIN Generation/Verification of PIN Offset Programmer’s Reference Manual March 18, 2021 Document Number: D998200466-11 REGISTERED TO ISO 9001:2015 Magensa, LLC I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350 www.magtek.com Copyright © 2006 - 2021 MagTek, Inc. Printed in the United States of America INFORMATION IN THIS PUBLICATION IS SUBJECT TO CHANGE WITHOUT NOTICE AND MAY CONTAIN TECHNICAL INACCURACIES OR GRAPHICAL DISCREPANCIES. CHANGES OR IMPROVEMENTS MADE TO THIS PRODUCT WILL BE UPDATED IN THE NEXT PUBLICATION RELEASE. NO PART OF THIS DOCUMENT MAY BE REPRODUCED OR TRANSMITTED IN ANY FORM OR BY ANY MEANS, ELECTRONIC OR MECHANICAL, FOR ANY PURPOSE, WITHOUT THE EXPRESS WRITTEN PERMISSION OF MAGTEK, INC. MagTek®, MagnePrint®, and MagneSafe® are registered trademarks of MagTek, Inc. Magensa™ is a trademark of MagTek, Inc. DynaPro™ and DynaPro Mini™, are trademarks of MagTek, Inc. ExpressCard 2000 is a trademark of MagTek, Inc. IPAD® is a trademark of MagTek, Inc. IntelliStripe® is a registered trademark of MagTek, Inc. AAMVA™ is a trademark of AAMVA. American Express® and EXPRESSPAY FROM AMERICAN EXPRESS® are registered trademarks of American Express Marketing & Development Corp. D-PAYMENT APPLICATION SPECIFICATION® is a registered trademark to Discover Financial Services CORPORATION MasterCard® is a registered trademark and PayPass™ and Tap & Go™ are trademarks of MasterCard International Incorporated. Visa® and Visa payWave® are registered trademarks of Visa International Service Association. MAS-CON® is a registered trademark of Pancon Corporation. Molex® is a registered trademark and PicoBlade™ is a trademark of Molex, its affiliates, related companies, licensors, and/or joint venture partners. ANSI®, the ANSI logo, and numerous other identifiers containing "ANSI" are registered trademarks, service marks, and accreditation marks of the American National Standards Institute (ANSI). ISO® is a registered trademark of the International Organization for Standardization. UL™ and the UL logo are trademarks of UL LLC. PCI Security Standards Council® is a registered trademark of the PCI Security Standards Council, LLC. EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. The Contactless Indicator mark, consisting of four graduating arcs, is a trademark owned by and used with permission of EMVCo, LLC. The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by MagTek is under license. Google Play™ store, Google Wallet™ payment service, and Android™ platform are trademarks of Google Inc. Apple Pay®, iPhone®, iPod®, Mac®, and OS X® are registered trademarks of Apple Inc., registered in the U.S. and other countries. iPad™ is a trademark of Apple. Inc. App StoreSM is a service mark of Apple Inc., registered in the U.S. and other countries. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used by Apple Inc. under license. Microsoft®, Windows®, and .NET® are registered trademarks of Microsoft Corporation. All other system names and product names are the property of their respective owners. Magensa QwickPIN| Generation/Verification of PIN Offset | Programmer’s Reference Manual Page 2 of 23 (D998200466-11) Table 0-1 - Revisions Rev Number Date Notes Initial Release. This version of document is compatible with 10 March 2021 QwickPIN API version 1.2.0.1 11 March 2021 Data Magensa QwickPIN| Generation/Verification of PIN Offset | Programmer’s Reference Manual Page 3 of 23 (D998200466-11) 0 - Table of Contents Table of Contents Table of Contents .............................................................................................................................................. 4 1 Introduction ............................................................................................................................................... 5 2 QwickPIN Operations ............................................................................................................................... 7 2.1 /api/PINOffset/Generate ................................................................................................................ 7 2.1.1 INPUT PROPERTIES ................................................................................................................. 7 2.1.2 OUTPUT PROPERTIES .............................................................................................................. 7 2.2 /api/PINOffset/Verify ...................................................................................................................... 9 2.2.1 INPUT PROPERTIES ................................................................................................................. 9 2.2.2 OUTPUT PROPERTIES .............................................................................................................. 9 3 Error Codes and Reasons ...................................................................................................................... 11 3.1 Sample Error Response ................................................................................................................. 11 3.2 Error Codes and Reasons .............................................................................................................. 12 4 IP Whitelist............................................................................................................................................... 13 Appendix A PAN Data ................................................................................................................................. 14 Appendix B PIN Data .................................................................................................................................. 18 Appendix C Postman .................................................................................................................................. 20 Appendix D Glossary of Terms .................................................................................................................. 22 Appendix E References .............................................................................................................................. 23 Magensa QwickPIN| Generation/Verification of PIN Offset | Programmer’s Reference Manual Page 4 of 23 (D998200466-11) 1 - Introduction 1 Introduction The purpose of this document is to describe the main operations available in Magensa QwickPIN Web service and their required & optional input/output parameters. It also provides sample REST requests & responses as reference for client developers. It also includes error codes, reasons, and a sample error response. QwickPIN Web service enables clients to easily generate & verify the PIN Offset via Basic Authentication if required fields are inputted correctly. QwickPIN Web Service has IP Whitelist feature so it will check for specific IP addresses and rejects any incoming data that does not originate from one of the authorized IP addresses. Please refer to chapter 4 for more detail information. QwickPIN Web service end point provides swagger documentation and swagger.json which can be imported to Postman program. Please refer to Appendix C for how to import swagger.json to Postman. This service comprises of two APIs, one is for generation of PIN Offset and the other one is for verification of PIN Offset. The input format for Verification API is the same as Generation API with an extra input for “RefPINOffset” which will be used for verification process. RefPINOffset is a required field with QwickPIN API ver 1.2.0.1. Depending on PAN Data Type, the format of PAN Data will be different. PAN Data Type can be one of the following: • MagtekARQC • MagTekTrack2Encrypted • DukptPAN MagTekARQC is the ARQC data in TLV format generated from MagTek Reader (EMV dip or Fallback MSR Swipe). MagTekTrack2Encrypted is the regular MSR Swipe where Encrypted Track2 and MSR KSN are available. TokenV2 can be used to encrypt track2 for this option. Please refer to Appendix A for how to encrypt track2 with TokenV2 service. DUKPT PAN is a value where a client will encrypt the data (concatenated values of PAN, Exp Date and Service Code) under DUKPT. Exp Date and Service Code, however, are not required for generating/verifying PINOffset. To know more about building PAN Data, please refer to Appendix A in this document. Each decrypted PAN can be validated by Luhn Algorithm or Modulus 10 algorithm in BIN level. It’s up to clients for enabling/disabling it. If clients have multiple BINs, each BIN has Luhn Check option separately. Input parameter RefID allows a customer to provide a reference ID to link its financial system to Magensa service. It can be a GUID or any other information a customer wants to use. Input parameter PIN DataType is used for PIN block format. Although the most common PIN Block encoding format is ISO_0 type, QwickPIN supports ISO 0, ISO 1, ISO 2, and ISO 3. For PIN Data, Magensa currently supports 4-digit PIN that is enclosed in the Encrypted PIN Block. PIN Block needs to be encrypted under DUKPT key with pin variant. Conditionally, PIN Data requires a json string which contains both EPB and KSN. PIN Data can also be obtained from TokenV2 when plain PIN block is sent to TokenV2 for encryption. Please refer to Appendix B for how to build plain PIN block and to obtain Encrypted PINBlock. Magensa QwickPIN|