Dev Guide for Encrypted Swipe

Transcription

1 Dev Guide for Encrypted Swipe Version 1.5 Last Updated: 20 th August 2014

2 Table of Contents 1 Introduction Important notes Concept Overview Encrypted Swipe Devices Magtek Devices Magtek udynamo Mobile phone (audio port) card swipe Magtek Dynamag USB Encrypted swiper IDTech Devices IDTech UniMag II audio port swiper IDTech SecureMag USB card swipe Submitting a Transaction using the Encrypted Swipe Processing single CC transactions Processing a CC and creating a Token Create a Token only Testing Test Card Test Data Magtek udynamo Mobile Magtek Dynamag USB IDTech UniMag II Mobile Swiper IDTech SecureMag USB Swiper Rejection codes for Credit Card Responses Page 2 of 19

3 1 Introduction This user guide describes the development required to process credit card transactions via an encrypted swipe device using our ProcessLink WebServices. The encrypted swipe devices are designed to work with the iats WebService ProcessLink. (Details on ProcessLink can be found in our ProcessLink Guide and is available to download from the iats Developer Site here. For assistance, please Our encrypted swipe devices are fully PCI compliant as the sensitive credit card data is encrypted immediately within the device before the data flows through to the computer or device which means your servers do not have to handle any clear text credit card data. Page 3 of 19

4 2 Important notes Please note that you do not need to pass CVV, MOP or Expiry date when sending iats the encrypted data string. It is not necessary to pass the FirstName or LastName of the customer through the API either. If you don t, then the name on the card will be used. If you do pass the names through, they will overwrite the name on the card. iats provides two types of card swipers: 1. Magtek for USB and Mobile applications 2. IDTech for USB and Mobile applications To correctly decrypt the data for the transaction, iats requires the swiper type to be added to encryption string that gets sent through to iats. Below are the swiper numbers required depending on the device being used: Swiper Code IDTech SecureMag USB swiper 00 IDTech UniMag mobile swiper 01 MagTek Dynamag USB swiper 02 MagTek udynamo mobile swiper 03 Page 4 of 19

5 3 Concept Overview When a credit card it swiped, the swiper will read and encrypt the track information on the credit card magnetic strip andpass the encrypted credit card track information to the creditcardnum or ccnum parameter ( to the relevant web service to either a) process the transaction directly or b) tokenize the details for future transactions. The swipe cannot be used to create recurring Customer Code Tokens where iats holds the processing schedule at this time, but will be available in a future update. The Encrypted Swipe devices can currently be used with the following ProcessLink services: Processing a single credit card transaction (available only for NA processing) ProcessCreditCardV1 Creating a token and immediately processing a single credit card transaction (available for only NA processing) CreateCustomerCodeAndProcessCreditCardV1 Create a token only is being developed CreateCreditCardCustomerCodeV1 Page 5 of 19

6 4 Encrypted Swipe Devices 4.1 Magtek Devices Magtek udynamo Mobile phone (audio port) card swipe The Magtek udynamo uses the audio port to send the encrypted details to the app. Full details on the udynamo can be found here: Page 6 of 19

7 Development requirements Magtek are specific in their SDK with regards to the data that they send. TheMagtek, SDK can collect the following fields from each swipe: [self.mtscralib gettrackdecodestatus], [self.mtscralib getmaskedtracks], [self.mtscralib gettrack1masked], [self.mtscralib gettrack2masked], [self.mtscralib gettrack1], [self.mtscralib gettrack2], [self.mtscralib gettrack3], [self.mtscralib getcardiin], [self.mtscralib getcardname], [self.mtscralib getcardlast4], [self.mtscralib getcardexpdate], [self.mtscralib getcardservicecode], [self.mtscralib getcardpanlength], [self.mtscralib getksn], [self.mtscralib getdeviceserial], [self.mtscralib getmagneprint], [self.mtscralib getmagneprintstatus], [self.mtscralib getsessionid], [self.mtscralib getdevicename]]; iats however only need the following fields to be send via the API: [self.mtscralib gettrack1], [self.mtscralib gettrack2], [self.mtscralib getksn], iats also requires some additional details including some parsing delimiters. For Magtek udynamos, please collate the data in the following order and delimitation: KSN Where: - SwiperType : 03 for Magtek udynamo - gettrack1 : Encrypted Track 1 data - gettrack2 : Encrypted Track 2 data - KSN : KSN data : Delimiter Example: B34243FF Page 7 of 19

8 4.1.2 Magtek Dynamag USB Encrypted swiper The Magtek Dynamag is a USB encrypted swiper for use on PC s. Full details on the Dynamag can be found here: Development requirements When you swipe the USB device a complete string of masked as well as encrypted data. You can use the masked data for the name of the client, the expiry date and last 4 digits of the credit card. Unlike the Mobile swipers where you need to parse out certain information, for the USB swipers the entire string (masked and encrypted) needs to be passed through to iats. Magtek USB encrypted swipe example: %B ^YOU/A GIFT FOR^ ?; = ? F2E44C1E BC0 8BB06CE1A9CD897EC00E2BB035C6D9FDF625F7AF63034BDBEC092D8C035B05301A89C056854B6EC CE07AD5E585E4E37E2867B3 2CAF4061ACD747C310DA546974D045C8C446C7C6B8577B D3C33B 0CEBAC0147D7B489EAE E005095F7A5E2F9B3076FBA250877E9105BEE932ABF6A0F02B7D1695 9F CA573B81CE4ED3CF0BC0FA1B3067C034A946E9F80F3D7B For the Magtek Dynamag, please collate the data in the following order and delimitation: Entire USB output Page 8 of 19

9 Where: - SwiperType : 02 for Magtek Dynamag - Entire USB output string (no parsing) : Delimiter Example: %B ^YOU/A GIFT FOR^ ?; = ? F2E44C1E BC0 8BB06CE1A9CD897EC00E2BB035C6D9FDF625F7AF63034BDBEC092D8C035B05301A89C056854B6EC CE07AD5E585E4E37E2867B3 2CAF4061ACD747C310DA546974D045C8C446C7C6B8577B D3C33B 0CEBAC0147D7B489EAE E005095F7A5E2F9B3076FBA250877E9105BEE932ABF6A0F02B7D1695 9F CA573B81CE4ED3CF0BC0FA1B3067C034A946E9F80F3D7B Page 9 of 19

10 4.2 IDTech Devices IDTech UniMag II audio port swiper IDTech UnimagII uses the audio port to communicate with the app. Full details on the Unimag II can be found here: Development requirements When you swipe your credit card, IDTech will read, mask some information and encrypt all track information.. See screenshot below from a demo application showing the masked information above and encrypted data below (in red box): Page 10 of 19

11 Make sure to parse out and only pass in the encrypted credit card track information (enclosed with red rectangle in the diagram above) to the creditcardnum or ccnum parameter of web service method. You can use the unencrypted (masked) data to fill fields for the customer to verify, such as the last 4 digits of the Credit card, the first name and last name. Example of encrypted data from IDTech Unimag: <02f f a a2a2a2a 2a2a2a2a e d454e f e a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b a2a2a 2a2a2a2a 2a d a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df d3c14 a769b2c c4 97dbffc2 3890bd8e 1373fb2c e6a4fd03 23be5966 9ff8bd a4c 2c3d ffff c8 2403> iats requires this encrypted data and the swiper type and this encrypted data to complete the transaction. Please parse the information as follows: EncryptedCode Where: - SwiperType : 01 for IDTech UnimagII - Entire Encrypted string (no masked data) : Delimiter Example: 02f f a a2a2a2a 2a2a2a2a e d454e f e a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b a2a2a 2a2a2a2a 2a d a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df d3c14 a769b2c c4 97dbffc2 3890bd8e 1373fb2c e6a4fd03 23be5966 9ff8bd a4c 2c3d ffff c Page 11 of 19

12 4.2.2 IDTech SecureMag USB card swipe The IDTech Secure Mag is a USB encrypted swipe for PC s and Laptops More details can be found here: securemag.html Development requirements When you swipe the USB device a complete string of masked as well as encrypted data. You can use the masked data for the name of the client, the expiry date and last 4 digits of the credit card. Unlike the Mobile swipers where you need to parse out certain information, for the USB swipers the entire string (masked and encrypted) needs to be passed through to iats. IDTECH USB encrypted swipe example: 02A001801F3B B%*4941********5889^YOU/A GIFT FOR^***********************?*;4941********5889=***************?*ACC8778A7A496718C9EF3F E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F010B9E9DB243DBD3EB56825B6 F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA D640B46EDA8E6 C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B A39DA8FFFF D68AA03 For the IDTech Secure Mag, please collate the data in the following order and delimitation: Entire USB output Page 12 of 19

13 Where: - SwiperType : 00 for IDTech Secure Mag - Entire USB output string (no parsing) : Delimiter Example: 02A001801F3B B%*4941********5889^YOU/A GIFT FOR^***********************?*;4941********5889=***************?*ACC8778A7A496718C9EF3F E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F010B9E9DB243DBD3EB56825B6 F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA D640B46EDA8E6 C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B A39DA8FFFF D68AA03 Page 13 of 19

14 5 Submitting a Transaction using the Encrypted Swipe 5.1 Processing single CC transactions This service is used when you want to make a single transaction by swiping a credit card. This is when you want to do a one-off credit card transaction without needing a Token (Customer Code) to be used or created. To use the encrypted swipe feature for a single CC transaction, you will use the ProcessLink ProcessCreditCardV1 SOAP call. The encrypted data needs to be added to the creditcardnum field, highlighted below. POST /NetGate/ProcessLink.asmx HTTP/1.1 Host: Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <ProcessCreditCardV1 xmlns=" <agentcode>string</agentcode> <password>string</password> <customeripaddress>string</customeripaddress> <invoicenum>string</invoicenum> <creditcardnum>string</creditcardnum> <creditcardexpiry>string</creditcardexpiry> <cvv2>string</cvv2> <mop>string</mop> <firstname>string</firstname> <lastname>string</lastname> <address>string</address> <city>string</city> <state>string</state> <zipcode>string</zipcode> <total>string</total> <comment>string</comment> </ProcessCreditCardV1> </soap12:body> </soap12:envelope> For Example with the IDTech SecureMag the string would be: 02A001801F3B B%*4941********5889^YOU/A GIFT FOR^***********************?*;4941********5889=***************?*ACC8778A7A496718C9EF3F E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F010B9E9DB243DBD3EB56825B6 F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA D640B46EDA8E6 C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B A39DA8FFFF D68AA03</creditCardNum> Page 14 of 19

15 5.2 Processing a CC and creating a Token This service is for when you want to create a credit card Token (Customer Code) (Note: no recurring transactions will be set up with this process) and to process a credit card transaction at the same time. This is useful if you want to do an immediate transaction, but store the Token for future transactions without need to store the clear text credit card details. To use the encrypted swipe feature, you need to first write the code to process a single credit card transaction using ProcessLink, CreateCustomerCodeAndProcessCreditCardV1 instructions. The encrypted data needs to be added to the ccnum field, highlighted below. POST /NetGate/ProcessLink.asmx HTTP/1.1 Host: Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <CreateCustomerCodeAndProcessCreditCardV1 xmlns=" <agentcode>string</agentcode> <password>string</password> <customeripaddress>string</customeripaddress> <invoicenum>string</invoicenum> <ccnum>string</ccnum> <ccexp>string</ccexp> <firstname>string</firstname> <lastname>string</lastname> <address>string</address> <city>string</city> <state>string</state> <zipcode>string</zipcode> <cvv2>string</cvv2> <total>string</total> </CreateCustomerCodeAndProcessCreditCardV1> </soap12:body> </soap12:envelope> For Example with the IDTech Unimag mobile swiper: < 02f f a a2a2a2a 2a2a2a2a e d454e f e a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b a2a2a 2a2a2a2a 2a d a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df d3c14 a769b2c c4 97dbffc2 3890bd8e 1373fb2c e6a4fd03 23be5966 9ff8bd a4c 2c3d ffff c8 2403</ccNum> Page 15 of 19

16 5.3 Create a Token only This service is used when you do not want to process a transaction immediately, but only create a token to store on your dbase. This token can then be used for single transactions or recurring transactions where you manage the recurring schedule. The SOAP service call for this will use the CustomerLink CreateCreditCardCustomerCodeV1 SOAP call. POST /NetGate/CustomerLink.asmx HTTP/1.1 Host: Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <CreateCreditCardCustomerCodeV1 xmlns=" <agentcode>string</agentcode> <password>string</password> <customeripaddress>string</customeripaddress> <customercode>string</customercode> <firstname>string</firstname> <lastname>string</lastname> <companyname>string</companyname> <address>string</address> <city>string</city> <state>string</state> <zipcode>string</zipcode> <phone>string</phone> <fax>string</fax> <alternatephone>string</alternatephone> < >string</ > <comment>string</comment> <recurring>boolean</recurring> <amount>string</amount> <begindate>datetime</begindate> <enddate>datetime</enddate> <scheduletype>string</scheduletype> <scheduledate>string</scheduledate> <creditcardcustomername>string</creditcardcustomername> <creditcardnum>string</creditcardnum> <creditcardexpiry>string</creditcardexpiry> <mop>string</mop> </CreateCreditCardCustomerCodeV1> </soap12:body> </soap12:envelope> For Example with the MagTek udynamo the string would be: B34243FF</creditCardNum> Notes: To create a Token only, set the recurring flag to False. It is possible to set up a recurring schedule with this call as well by setting the recurring flag to True and supplying the amount, start and end dates, schedule type and schedule date. Refer to the iats CustomerLink documents for further details on this. Page 16 of 19

17 6 Testing 6.1 Test Card The TEST88 iats Client Code has been created to allow for testing systems, and can be used with encrypted swipe. iats can supply test credit cards with the correct test numbers, ie and Please contact iats if you require these test cards. User ID Password URL: = TEST88 = TEST88 NA = UK = Test Data Below is test data for each of the swipers you can use for testing (if you don t have a test card or swiper). The following details are in the encrypted data: First Name: IATS Last Name: PAYMENTSTESTCARD Card number: Expiry date: 21/08 (YY/MM) Magtek udynamo Mobile KSN: B1D54BC Track1.Encrypted: C4DDC3DE59B1DB65F03D04CFF145469CBB2CB59E22BA56ED8691D27813D963F51408F5BDDEB03E0B1860E FAAD85F9FA78ED D4ACE1F585C194DEE2D7F ABB9 Track2.Encrypted: FADF BB07D444459D4DBEDC0EE099322D1AA7FBC64CDBFE A592E52BFC8EE95 Page 17 of 19

18 6.2.2 Magtek Dynamag USB %B ^PAYMENTSTESTCARD/IATS^ ?; = ? B44E25D C8CA860B1789E689CC88FF3451E0F851FD046C884DE8AAAF 3B69D89BE14B024ED7472A589702A0406C D7991DEDB140BC86A1755EAEF4C0AB88D 8237C3C3 FE B500DDDAB5861F506B073A5B09A919AFBA D4008FEB5D78D B0ACA041688D5E CE957D D6331C1E8B7B1C4367B6358B22A762B03CE4DDB23CDBB C51B79DFE B2504E AA 46F561D890ED B2504E BA7C IDTech UniMag II Mobile Swiper 02f f a a2a2a2a 2a2a2a2a e d454e f e a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b a2a2a 2a2a2a2a 2a d a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df d3c14 a769b2c c4 97dbffc2 3890bd8e 1373fb2c e6a4fd03 23be5966 9ff8bd a4c 2c3d ffff c IDTech SecureMag USB Swiper 02B701801F B%*4111********1111^PAYMENTSTESTCARD/IATS^***********************?* ;4111********1111=***************?*D9DC9EFFAC215F5997B6C8FE81559E E73591F F F001225A7B9D71783A7BB6B073F06578EA6C668F368FACCEA6EADD953818D3F3A6FE47EB580D1433D906F D732CCCC280D68B25E A55D138E2EAA59AF53C7C690924C67DCDB76419EAF661F5DF D C06A05CA81AA62361BA02901DF2197F795D78CFA64FA48CF0624FA81CA E4F1FFFF A Page 18 of 19

19 6.3 Rejection codes for Credit Card Responses Below is the list of transaction rejection codes that may be received for processing on a live merchant account. This list can be downloaded here: Page 19 of 19