For new mobile app integrations, we recommend using the Bolt Mobile SDKs to securely encrypt and tokenize customers' payment card data.

Overview

For integrators that do not require advanced features (like support for EMV, NFC, and PIN-Debit) CardSecure supports a simple integration to MagTek devices (USB or Mobile) for use in third-party applications.

By following the steps in this guide, you can successfully extract card data from a supported magstripe reader for authorization and/or tokenization.

Supported Devices

CardSecure supports integrations to the following USB and mobile magstripe devices:

Device Type	Connection Type
MagnaSafe	USB
iDynamo4	30 Pin
iDynamo5	Lightning
uDynamo	Auxillary

This guide describes integrations for both encrypted and unencrypted devices. Encrypted devices are injected with the necessary encryption keys and procured by CardPointe Support.

Process Overview

Retrieve track data from Magstripe Reader (MSR) device
For mobile devices:
- Format pertinent data fields into pipe delimited string recognized by CardSecure and the CardPointe Gateway.
Send the string in one of the following request types:
- Tokenization Request to CardSecure (retrieve a token)
- Authorization Request to the CardPointe Gateway(submit for payment)

Retrieve Track Data from MSR

Encrypted MagTek USB Devices

When using encrypted MagnaSafe USB card readers, simply retrieve the track data as-is and pass the entire string within the "track" parameter of an authorization request

Unencrypted MagTek USB Devices

When using unencrypted MagnaSafe USB cared readers, only track 2 data (including sentinel characters) is required within the track parameter of an authorization request.

The following string is an example of Track 2 data bring retrieved from an unencrypted USB reader:

;4761739001010010=18122011143878001629?

Track 2 Data Structure

Field Name	Length	Description
Start Sentinel (SS)	1 character	Indicates the beginning of Track 2; set to ";"
Primary Account Number (PAN)	up to 19 digits	Always numerical; usually set to the credit/debit card number
Field Separator (FS)	1 character	Delimits Track 2 fields; set to "="
Expiration Date (ED)	4 digits	Always in the format YYMM
Service Code (SC)	3 digits	Indicates what types of charges can be accepted
Discretionary Data (DD)	Variable*	Determined by card issuer--may include Card Code and/or PINs
End Sentinel (ES)	1 character	Indicates the end of Track 2; set to "?"
Longitude Redundancy Check (LRC)	1 character	Used to verify that Track 2 was read accurately

Track 2 Data cannot exceed 40 characters, including all sentinels, the field separator, and the LRC. The length of discretionary data is restricted as a result and tends to hold fairly short values.

Encrypted MagTek Mobile Devices

MagTek provides documentation, SDKs, and examples on their Support site that will help guide your integration with their Mobile MSR readers.

The following example response illustrates response data retrieved from a Visa card (acquirer's test card) through MagTek’s Android SDK demo:

Response.Length=578
EncryptionStatus=0206
SDK.Version=101.18
Reader.Type=1
Track.Status=000002
KSN=9010010B1C067E000023
Track1.Masked=%B4761730001000036^VISA ACQUIRER TEST CARD 03^1512201000000000000000000000000?
Track2.Masked=;4761730001000036=15122010000000000000?
Track3.Masked=
Track1.Encrypted=7BB0FEC3FE7F0BE5C36829C3DDD05216536E03C4B4357C45DB6BCC4DBDC8FC6862D093B236BBCE552E913442431581E7592C551D0CBB77DF92606D178F4F5C4B8976387EE6A944DD
Track2.Encrypted=695FAB9426A69E126AECEB18D4D7389A7A3B6CFB612FE44A239C930CEB0D2A520E682AEDAAA79B64
Track3.Encrypted=
MagnePrint.Encrypted=
MagnePrint.Status=
Card.IIN=476173
Card.Name=VISA ACQUIRER TEST CARD 03
Card.Last4=0036
Card.ExpDate=1512
Card.SvcCode=201
Card.PANLength=16
Device.Serial=F723A60410003300
SessionID=
Card.Status=00
Firmware.Partnumber=21043017A01
MagTek.SN=
TLV.Version=0002
HashCode=
Response.Raw=C10182011CC30234810902000281030B32313034333031374130318104134D616754656B206144796E616D6F2056312E308140016481410400000010C2010F800102020682610100826203000002C2023E82411A5649534120414351554952455220544553542043415244203033824206343736313733824304303033368244043135313282450332303182460110C203818E810108F723A6041000330083010A9010010B1C067E000023830A487BB0FEC3FE7F0BE5C36829C3DDD05216536E03C4B4357C45DB6BCC4DBDC8FC6862D093B236BBCE552E913442431581E7592C551D0CBB77DF92606D178F4F5C4B8976387EE6A944DD830B28695FAB9426A69E126AECEB18D4D7389A7A3B6CFB612FE44A239C930CEB0D2A520E682AEDAAA79B64

Formatting Response Data Into a String

For mobile MagTek devices using the MagTek SDK, you must retrieve and construct a pipe delimited string in the format we recognize for Magtek. That string format is as follows (without the brackets):

[Track1Masked][Track2Masked]|0600|[Track1Encrypted]|[Track2Encrypted]||||||[KSN]||

Following this format, the pipe delimited string for the data retrieved in the above example is as follows:

%B4761730001000036^VISA ACQUIRER TEST CARD 03^1512201000000000000000000000000? ;4761730001000036=15122010000000000000|0600|7BB0FEC3FE7F0BE5C36829C3DDD05216536E03C4B4357C45DB6BCC4DBDC8FC6862D093B236BBCE552E913442431581E7592C551D0CBB77DF92606D178F4F5C4B8976387EE6A944DD|695FAB9426A69E126AECEB18D4D7389A7A3B6CFB612FE44A239C930CEB0D2A520E682AEDAAA79B64||||||9010010B1C067E000023||

Tokenization Request to CardSecure

The pipe delimited string must be URL Encoded and sent to CardSecure as follows:

https://fts.cardconnect.com:6443/cardsecure/cs?action=CZ&data={string}

A token is returned in response:

action=CZ&data=9373873897361002

Authorization Request to the CardPointe Gateway

You can submit either the encrypted string containing track data or a token from CardSecure in an authorization request to the CardPointe Gateway, as detailed below.

Authorization with Encrypted Track Data

Sample Authorization Request with Encrypted Track Data

{
    "merchid": "496160876666",
    "accttype": "Visa",
    "account": "",
    "expiry": "",
    "amount": "2.50",
    "currency": "USD",
    "name": "DOROTHY BEDFORD",
    "Address": "123 MAIN STREET",
    "city": "WEST CHESTER",
    "region": "PA",
    "Country": "USA",
    "track": "%B4761730001000010^TEST/CARD 02              ^1812000000000000000000000000000?;4761730001000010=18120000000000000000?|0600|B138B30821C4800546B63270CB8F780DAB612B080675975447253FEF45A342640F92BDDD0ED7A403784D7CF0C544505128B03FE7688B7BB32067EE700253505F2F35D01F1AF979C93C5AACE0C56D720C|E2647C1A6B481D7493BA81AD8857E38D36481BC63C84EE7F5998D819BF043955E29343B82D6F7202||61403000|0E76E17BCA66819589A0837216AB48E1A113C69EC08A0F5A9F8CBC81F0DB39E7798539EF3953FA3FB2AC510B9BD417560683578A6D6B202D|B36E5DA092616AA|8DF38D680DE373C2|9013050B36E5DA000003|AE7F||1000"
    "phone": "9725492001",
    "postal": "19380",
    "Ecomind": "E",
    "cvv2": "123",
    "orderid": "1696481",
    "capture": "Y"
}

Sample Authorization Response

{
    "amount": "2.50",
    "resptext": "Approval",
    "commcard": " C ",
    "cvvresp": "P",
    "batchid": "144",
    "avsresp": " ",
    "respcode": "00",
    "merchid": "496160876666",
    "token": "9431058263663773",
    "authcode": "PPS487",
    "respproc": "FNOR",
    "retref": "258925138081",
    "respstat": "A",
    "account": "9431058263663773"
}

Authorization with Unencrypted Track 2 data

Sample Authorization Request with Unencrypted Track 2 Data

{
    "merchid": "496160876666",
    "accttype": "Visa",
    "account": "",
    "expiry": "",
    "amount": "2.50",
    "currency": "USD",
    "name": "DOROTHY BEDFORD",
    "Address": "123 MAIN STREET",
    "city": "WEST CHESTER",
    "region": "PA",
    "Country": "USA",
    "track": ";4761739001010010=18122011143878001629?"
    "phone": "9725492001",
    "postal": "19380",
    "Ecomind": "E",
    "cvv2": "123",
    "orderid": "1696481",
    "capture": "Y"
}

Sample Authorization Response

{
  "amount": "2.50",
  "resptext": "Approval",
  "commcard": " C ",
  "cvvresp": "P",
  "batchid": "163",
  "avsresp": " ",
  "respcode": "00",
  "merchid": "496160876666",
  "token": "9477257372660010",
  "authcode": "PPS099",
  "respproc": "FNOR",
  "retref": "301428154502",
  "respstat": "A",
  "account": "9477257372660010"
}

Authorization with a CardSecure Token

When you retrieve a token from a card swipe, the token provided is stored with track data. The track data is sent with the first authorization that uses the token, resulting in a "card-present" qualification and discount rate.

The token should be populated in the "account" field.

Sample Request and Response Authorizations

Sample Authorization Request with a CardSecure Token

{
    "merchid": "496160876666",
    "accttype": "visa",
    "orderid": "AB-11-9876",
    "account": "9441149619831111",
    "expiry": "1018",
    "amount": "12.03",
    "currency": "USD",
    "name": "JOHNNY SMITH",
    "address": "123 MAIN STREET",
    "city": "WEST CHESTER",
    "region": "PA",
    "country": "US",
    "postal": "19406",
    "ecomind": "E",
    "cvv2": "123",
    "track": "null",
    "tokenize": "N",
    "capture": "N",
    "userfields": [{"custommerchant": "Acme Inc"}]
}

Sample Authorization Response

{
    "amount": "12.03",
    "resptext": "Approval",
    "commcard": " C ",
    "cvvresp": "M",
    "avsresp": "Y",
    "respcode": "00",
    "merchid": "496160876666",
    "token": "9441149619831111",
    "authcode": "PPS000",
    "respproc": "FNOR",
    "retref": "258939237963",
    "respstat": "A",
    "account": "9441149619831111"
 }