Developers - Direct Integration - Encrypted Magnetic Card Readers

ENCRYPTED MAGNETIC STRIPE READERS

Our encrypted magnetic stripe readers (MSRs) 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. This means your servers don't have to handle any clear text credit card data. The encrypted MSRs are designed to work with the iATS Web service - ProcessLink. For further assistance, please email webservice@iatspayments.com.

Please note: Brickwork, the iATS Payments application for Salesforce, does not currently support encrypted magnetic stripe readers. We hope to add this functionality in the near future. Please review our Brickwork user guide to learn more about using non-encrypted magnetic stripe readers in Brickwork. When a credit card is swiped through the MSR, it will read and encrypt the track data on the magnetic stripes and pass the encrypted data 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.

FULL DEVELOPMENT GUIDE

The complete development guide, including details on how to submit the details/parameters via the above supported devices, is here.

Introduction

This user guide describes the development required to process credit card transactions via an iATS Payments 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.

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:

Magtek for USB and Mobile applications
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

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

ENCRYPTED SWIPE DEVICES

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.

uDynamo

Full details on the uDynamo can be found here.

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|@|C4DDC3DE59B1DB65F03D04CFF145469CBB2CB59E22BA56ED8691D27813D963F51408F5BDDEB03E0B1860EFAAD85F9FA78ED32911443282D4ACE1F585C194DEE2D7F473456972ABB9|@|FADF1842439903BB07D444459D4DBEDC0EE099322D1AA7FBC64CDBFE834511632A592E52BFC8EE95|@|9012910B1D54BC000069

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:

%B4111110009001111^PAYMENTSTESTCARD/IATS^21080000000000000000000?;4111110009001111=210800000000000?|0600|407B44E25D4237054896C8CA860B1789E689CC88FF3451E0F851FD046C884DE8AAAF3B69D89BE14B024ED7472A589702A0406C103714006D7991DEDB140BC86A1755EAEF4C0AB88D|8237C3C3FE1541620565B500DDDAB5861F506B073A5B09A919AFBA71446178D4008FEB5D78D13414||61403000|64616B0ACA041688D5E98886893776CE957D94799082D6331C1E8B7B1C4367B6358B22A762B03CE4DDB23CDBB6471658C51B79DFE5976018|B2504E2022814AA|46F561D890ED9881|9012910B2504E2000026|BA7C||0000

For the Magtek Dynamag, please collate the data in the following order and delimitation:

SwiperType|@|Entire USB output

Where:

SwiperType : 02 for Magtek Dynamag
Entire USB output string (no parsing)
|@| : Delimiter

Example:

02|@|%B4111110009001111^PAYMENTSTESTCARD/IATS^21080000000000000000000?;4111110009001111=210800000000000?|0600|407B44E25D4237054896C8CA860B1789E689CC88FF3451E0F851FD046C884DE8AAAF3B69D89BE14B024ED7472A589702A0406C103714006D7991DEDB140BC86A1755EAEF4C0AB88D|8237C3C3FE1541620565B500DDDAB5861F506B073A5B09A919AFBA71446178D4008FEB5D78D13414||61403000|64616B0ACA041688D5E98886893776CE957D94799082D6331C1E8B7B1C4367B6358B22A762B03CE4DDB23CDBB6471658C51B79DFE5976018|B2504E2022814AA|46F561D890ED9881|9012910B2504E2000026|BA7C||0000

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):

cid:image003.jpg@01CF75A9.192C2500

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

IDTech SecureMag USB card swipe

The IDTech Secure Mag is a USB encrypted swipe for PC’s and Laptops.

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:

02B701801F422300039B%*4111********1111^PAYMENTSTESTCARD/IATS^***********************?*;4111********1111=***************?*D9DC9EFFAC215F5997B6C8FE81559E4731349E73591F1985105FF001225A7B9D71783A7BB6B073F06578EA6C668F368FACCEA6EADD953818D3F3A6FE47EB580D1433D906FD732CCCC280D68B25E91342088970A55D138E2EAA59AF53C7C690924C67DCDB76419EAF661F5DF9749154D84855231220C06A05CA81AA62361BA02901DF2197F795D78CFA64FA48CF0624FA81CA32573681E4F1FFFF7381390005A00003225803

For the IDTech Secure Mag, please collate the data in the following order and delimitation:

SwiperType|@|Entire USB output

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

SUBMITTING A TRANSACTION WITH THE ENCRYPTED SWIPE

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: www.iatspayments.com

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>

<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>

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: www.iatspayments.com
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://www.iatspayments.com/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>

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: www.iatspayments.com

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>

<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|@|C4DDC3DE59B1DB65F03D04CFF145469CBB2CB59E22BA56ED8691D27813D963F51408F5BDDEB03E0B1860EFAAD85F9FA78ED32911443282D4ACE1F585C194DEE2D7F473456972ABB9|@|FADF1842439903BB07D444459D4DBEDC0EE099322D1AA7FBC64CDBFE834511632A592E52BFC8EE95|@|9012910B1D54BC000069</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.

TESTING

Test Card

The TEST88 iATS Client Code has been created to allow for testing iATS Payments 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 = TEST88

Password = TEST88

URL: NA = www.iatspayments.com

UK = www.uk.iatspayments.com

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)

Magtek uDynamo Mobile

KSN:

9012910B1D54BC000069

Track1.Encrypted:

C4DDC3DE59B1DB65F03D04CFF145469CBB2CB59E22BA56ED8691D27813D963F51408F5BDDEB03E0B1860E FAAD85F9FA78ED32911443282D4ACE1F585C194DEE2D7F473456972ABB9

Track2.Encrypted:

FADF1842439903BB07D444459D4DBEDC0EE099322D1AA7FBC64CDBFE834511632A592E52BFC8EE95

Magtek Dynamag USB

%B4111110009001111^PAYMENTSTESTCARD/IATS^21080000000000000000000?;4111110009001111=210 800000000000?|0600|407B44E25D4237054896C8CA860B1789E689CC88FF3451E0F851FD046C884DE8AAAF 3B69D89BE14B024ED7472A589702A0406C103714006D7991DEDB140BC86A1755EAEF4C0AB88D|8237C3C3 FE1541620565B500DDDAB5861F506B073A5B09A919AFBA71446178D4008FEB5D78D13414||61403000|6461 6B0ACA041688D5E98886893776CE957D94799082D6331C1E8B7B1C4367B6358B22A762B03CE4DDB23CDBB 6471658C51B79DFE5976018|B2504E2022814AA|46F561D890ED9881|9012910B2504E2000026|BA7C||0000

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

IDTech SecureMag USB Swiper

02B701801F422300039B%*4111********1111^PAYMENTSTESTCARD/IATS^***********************?* ;4111********1111=***************?*D9DC9EFFAC215F5997B6C8FE81559E4731349E73591F1985105F F001225A7B9D71783A7BB6B073F06578EA6C668F368FACCEA6EADD953818D3F3A6FE47EB580D1433D906F D732CCCC280D68B25E91342088970A55D138E2EAA59AF53C7C690924C67DCDB76419EAF661F5DF9749154 D84855231220C06A05CA81AA62361BA02901DF2197F795D78CFA64FA48CF0624FA81CA32573681E4F1FFFF7 381390005A00003225803

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.