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:
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"
}