Dev Guide for Encrypted Swipe Version 1.5 Last Updated: 20 th August 2014
Table of Contents 1 Introduction... 3 2 Important notes... 4 3 Concept Overview... 5 4 Encrypted Swipe Devices... 6 4.1 Magtek Devices... 6 4.1.1 Magtek udynamo Mobile phone (audio port) card swipe... 6 4.1.2 Magtek Dynamag USB Encrypted swiper... 8 4.2 IDTech Devices... 10 4.2.1 IDTech UniMag II audio port swiper... 10 4.2.2 IDTech SecureMag USB card swipe... 12 5 Submitting a Transaction using the Encrypted Swipe... 14 5.1 Processing single CC transactions... 14 5.2 Processing a CC and creating a Token... 15 5.3 Create a Token only... 16 6 Testing... 17 6.1 Test Card... 17 6.2 Test Data... 17 6.2.1 Magtek udynamo Mobile... 17 6.2.2 Magtek Dynamag USB... 18 6.2.3 IDTech UniMag II Mobile Swiper... 18 6.2.4 IDTech SecureMag USB Swiper... 18 6.3 Rejection codes for Credit Card Responses... 19 Page 2 of 19
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 email webservice@iatspayments.com. 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
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
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
4 Encrypted Swipe Devices 4.1 Magtek Devices 4.1.1 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: http://www.magtek.com/v2/products/secure-card-reader-authenticators/udynamo.asp Page 6 of 19
4.1.1.1 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: SwiperType @ gettrack1masked @ gettrack2masked @ KSN Where: - SwiperType : 03 for Magtek udynamo - gettrack1 : Encrypted Track 1 data - gettrack2 : Encrypted Track 2 data - KSN : KSN data - @ : Delimiter Example: 03 @ a897dsafsad87f98sad7f @ qwe453ter3534te345 @ 9123423432B34243FF Page 7 of 19
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: http://www.magtek.com/v2/products/secure-card-reader-authenticators/dynamag.asp 4.1.2.1 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: %B4847350003009386^YOU/A GIFT FOR^21080000000000000000000?;4847350003009386=210800000000000? 0600 2F2E44C1E47851145BC0 8BB06CE1A9CD897EC00E2BB035C6D9FDF625F7AF63034BDBEC092D8C035B05301A89C056854B6EC427958 CE07AD5E585E4E37E2867B3 2CAF4061ACD747C310DA546974D045C8C446C7C6B8577B002511915D3C33B 0CEBAC0147D7B489EAE 61403000 6E005095F7A5E2F9B3076FBA250877E9105BEE932ABF6A0F02B7D1695 9F6935417CA573B81CE4ED3CF0BC0FA1B3067C034A946E9F80F3D7B For the Magtek Dynamag, please collate the data in the following order and delimitation: SwiperType @ Entire USB output Page 8 of 19
Where: - SwiperType : 02 for Magtek Dynamag - Entire USB output string (no parsing) - @ : Delimiter Example: 02 @ %B4847350003009386^YOU/A GIFT FOR^21080000000000000000000?;4847350003009386=210800000000000? 0600 2F2E44C1E47851145BC0 8BB06CE1A9CD897EC00E2BB035C6D9FDF625F7AF63034BDBEC092D8C035B05301A89C056854B6EC427958 CE07AD5E585E4E37E2867B3 2CAF4061ACD747C310DA546974D045C8C446C7C6B8577B002511915D3C33B 0CEBAC0147D7B489EAE 61403000 6E005095F7A5E2F9B3076FBA250877E9105BEE932ABF6A0F02B7D1695 9F6935417CA573B81CE4ED3CF0BC0FA1B3067C034A946E9F80F3D7B Page 9 of 19
4.2 IDTech Devices 4.2.1 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: http://www.idtechproducts.com/products/mobile-readers/138.html 4.2.1.1 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
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: <02f00080 1f422300 8383252a 34313131 2a2a2a2a 2a2a2a2a 31313131 5e504159 4d454e54 53544553 54434152 442f4941 54535e32 3130382a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b343131 312a2a2a 2a2a2a2a 2a313131 313d3231 30382a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df559488 433d3c14 a769b2c4 244829c4 97dbffc2 3890bd8e 1373fb2c 56706162 e6a4fd03 23be5966 9ff8bd73 71634a4c 2c3d4254 31343032 36333335 33ffff73 81390314 800007c8 2403> iats requires this encrypted data and the swiper type and this encrypted data to complete the transaction. Please parse the information as follows: SwiperType @ EncryptedCode Where: - SwiperType : 01 for IDTech UnimagII - Entire Encrypted string (no masked data) - @ : Delimiter Example: 01 @ 02f00080 1f422300 8383252a 34313131 2a2a2a2a 2a2a2a2a 31313131 5e504159 4d454e54 53544553 54434152 442f4941 54535e32 3130382a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b343131 312a2a2a 2a2a2a2a 2a313131 313d3231 30382a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df559488 433d3c14 a769b2c4 244829c4 97dbffc2 3890bd8e 1373fb2c 56706162 e6a4fd03 23be5966 9ff8bd73 71634a4c 2c3d4254 31343032 36333335 33ffff73 81390314 800007c8 2403 Page 11 of 19
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: http://www.idtechproducts.com/products/swipe-readerwriters/92- securemag.html 4.2.2.1 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: 02A001801F3B2300039B%*4941********5889^YOU/A GIFT FOR^***********************?*;4941********5889=***************?*ACC8778A7A496718C9EF3F0 42025E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F010B9E9DB243DBD3EB56825B6 F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA04879920D640B46EDA8E6 C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B896880 21519A39DA8FFFF738139000400000D68AA03 For the IDTech Secure Mag, please collate the data in the following order and delimitation: SwiperType @ Entire USB output Page 12 of 19
Where: - SwiperType : 00 for IDTech Secure Mag - Entire USB output string (no parsing) - @ : Delimiter Example: 00 @ 02A001801F3B2300039B%*4941********5889^YOU/A GIFT FOR^***********************?*;4941********5889=***************?*ACC8778A7A496718C9EF3F0 42025E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F010B9E9DB243DBD3EB56825B6 F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA04879920D640B46EDA8E6 C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B896880 21519A39DA8FFFF738139000400000D68AA03 Page 13 of 19
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="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:body> <ProcessCreditCardV1 xmlns="https:///netgate/"> <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: <creditcardnum>00 @ 02A001801F3B2300039B%*4941********5889^YOU/A GIFT FOR^***********************?*;4941********5889=***************?*ACC8778A7A496718C9EF3F0 42025E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F010B9E9DB243DBD3EB56825B6 F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA04879920D640B46EDA8E6 C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B896880 21519A39DA8FFFF738139000400000D68AA03</creditCardNum> Page 14 of 19
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="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:body> <CreateCustomerCodeAndProcessCreditCardV1 xmlns="https:///netgate/"> <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: < ccnum>01 @ 02f00080 1f422300 8383252a 34313131 2a2a2a2a 2a2a2a2a 31313131 5e504159 4d454e54 53544553 54434152 442f4941 54535e32 3130382a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b343131 312a2a2a 2a2a2a2a 2a313131 313d3231 30382a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df559488 433d3c14 a769b2c4 244829c4 97dbffc2 3890bd8e 1373fb2c 56706162 e6a4fd03 23be5966 9ff8bd73 71634a4c 2c3d4254 31343032 36333335 33ffff73 81390314 800007c8 2403</ccNum> Page 15 of 19
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="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:body> <CreateCreditCardCustomerCodeV1 xmlns="https:///netgate/"> <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> <email>string</email> <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: <creditcardnum>03 @ a897dsafsad87d7f @ qwe453r3534te345 @ 9123423432B34243FF</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
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 41111 and 42222. Please contact iats if you require these test cards. User ID Password URL: = TEST88 = TEST88 NA = UK = www.uk.iatspayments.com 6.2 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: 4111111111111111 Expiry date: 21/08 (YY/MM) 6.2.1 Magtek udynamo Mobile KSN: 9012910B1D54BC000069 Track1.Encrypted: C4DDC3DE59B1DB65F03D04CFF145469CBB2CB59E22BA56ED8691D27813D963F51408F5BDDEB03E0B1860E FAAD85F9FA78ED32911443282D4ACE1F585C194DEE2D7F473456972ABB9 Track2.Encrypted: FADF1842439903BB07D444459D4DBEDC0EE099322D1AA7FBC64CDBFE834511632A592E52BFC8EE95 Page 17 of 19
6.2.2 Magtek Dynamag USB %B4111110009001111^PAYMENTSTESTCARD/IATS^21080000000000000000000?;4111110009001111=210 800000000000? 0600 407B44E25D4237054896C8CA860B1789E689CC88FF3451E0F851FD046C884DE8AAAF 3B69D89BE14B024ED7472A589702A0406C103714006D7991DEDB140BC86A1755EAEF4C0AB88D 8237C3C3 FE1541620565B500DDDAB5861F506B073A5B09A919AFBA71446178D4008FEB5D78D13414 61403000 6461 6B0ACA041688D5E98886893776CE957D94799082D6331C1E8B7B1C4367B6358B22A762B03CE4DDB23CDBB 6471658C51B79DFE5976018 B2504E2022814AA 46F561D890ED9881 9012910B2504E2000026 BA7C 0000 6.2.3 IDTech UniMag II Mobile Swiper 02f00080 1f422300 8383252a 34313131 2a2a2a2a 2a2a2a2a 31313131 5e504159 4d454e54 53544553 54434152 442f4941 54535e32 3130382a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a2a2a 2a2a3f2a 3b343131 312a2a2a 2a2a2a2a 2a313131 313d3231 30382a2a 2a2a2a2a 2a2a2a2a 2a3f2a87 a8e39cfa b3ef0630 ee27e912 34ce82d8 5b689e5f 10365a78 4c7573d2 1398ac9d 9cc2cd87 5e05ba1f 4e845ee0 306cf707 ae02a247 b2cab73a 46a2b203 df559488 433d3c14 a769b2c4 244829c4 97dbffc2 3890bd8e 1373fb2c 56706162 e6a4fd03 23be5966 9ff8bd73 71634a4c 2c3d4254 31343032 36333335 33ffff73 81390314 800007c8 2403 6.2.4 IDTech SecureMag USB Swiper 02B701801F422300039B%*4111********1111^PAYMENTSTESTCARD/IATS^***********************?* ;4111********1111=***************?*D9DC9EFFAC215F5997B6C8FE81559E4731349E73591F1985105F F001225A7B9D71783A7BB6B073F06578EA6C668F368FACCEA6EADD953818D3F3A6FE47EB580D1433D906F D732CCCC280D68B25E91342088970A55D138E2EAA59AF53C7C690924C67DCDB76419EAF661F5DF9749154 D84855231220C06A05CA81AA62361BA02901DF2197F795D78CFA64FA48CF0624FA81CA32573681E4F1FFFF7 381390005A00003225803 Page 18 of 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: https:///portal/staticpages/rejectcodes Page 19 of 19