Encrypted Card Read
This method directs the card reader to prompt the cardholder to swipe the card through the magnetic swipe reader.
You can use this method to retrieve card data to integrate gift card or loyalty card support through Converge.
note
This method requires the following:
- a valid connected card reader
- a magnetic stripe card or card number for manual keyed entry
ROAM readers do not support manual entry for on-demand card read due to lack of a pinpad.
Code Samples
CWS
Request
Property | Description |
---|---|
method string | required | startCardReadOnCardReader |
requestId string | required | Transaction Request ID |
targetType string | required | cardReader |
parameters JSONObject | required | All relevant parameters to initiate an on-demand card read. |
retrievalModes string | optional | Type of Entry Valid values: - SWIPE - MANUALLY_ENTERED |
Response
Property | Description |
---|---|
requestId string | Transaction Request ID As specified in the request. |
statusDetails string | Request Status |
data JSONObject | Object holding various responses. |
lastName string | Cardholder’s Last Name |
expirationDate string | Card Expiry Date |
encryptedTrack1Data string | Encrypted Track I Data |
ksn string | Key Serial Number |
firstName string | Cardholder’s First Name |
encryptedTrack2Data string | Encrypted Track II Data |
encryptedCombineTrack1Data string | Combine Track Data |
trackDataFormat string | Track Data Format |
maskedPAN string | Masked Card Number |
cardEncryptionFormat string | Card Data Encryption Method Valid values: - NONE - INGENICO_GENERIC_TDES - ROAM_GENERIC_TDES |
source string | Card Data Source |
serviceCode string | Service Code |
cardType string | Card Type |
Example
Request
{
"method" : "startCardReadOnCardReader",
"requestId" : "715270350",
"targetType" : "cardReader",
"version" : "1.0",
"parameters" : {
"retrievalModes" : [ "SWIPE" ]
}
}
Response
{
"requestId" : "1613289883",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"cardReaderCommand" : {
"eventQueue" : [ {
"timeStamp" : "1471902784093",
"statusDetails" : "CARD_SWIPED"
}, {
"timeStamp" : "1471902784093",
"statusDetails" : "CARD_ENTRY_COMPLETED"
} ],
"id" : "1613289880",
"cardData" : {
"lastName" : "******",
"expirationDate" : "******",
"encryptedTrack2Data" : null,
"firstName" : "******",
"ksn" : "******",
"encryptedTrack1Data" : null,
"encryptedCombineTrack1Data" : "394AAE707BBCF2A02B2AD9ADFB8AF9A8397EF584A0656BB4FA4685F290C0E99C4ED24C0DEEF3BF877EEC247BCB352F57258F9B4FB583F47EA9454C755BBE38BE8A435D7376ECE015726ED65D502CCE400AAAE5412491564CEE14531D42EA3F237C9CA31EAF02197661F60AD5A66CF5E4DF52BC5740A74D4B",
"trackDataFormat" : "INGENICO_RBA_TRACK_GENERIC",
"cardEncryptionFormat" : "INGENICO_GENERIC_TDES",
"maskedPan" : "******",
"source" : "SWIPE",
"serviceCode" : "101",
"cardType" : null
},
"completed" : true
}
}
}
Java
You need to set up a delegate to implement ECLCardReaderRetrieveCardDataListener
and pass it to retrieveCardData
function of card reader protocol. The card data will be available in delegate’s cardReaderProvidedSwipeData
call back.
private EnumSet<ECLCardEntryType> cardEntryTypes;
cardEntryTypes.add(ECLCardEntryType.SWIPE);
account.getCardReaders().getSelectedDevice().retrieveCardData(new ECLCardReaderRetrieveCardDataListener(), cardEntryTypes);
@Override public void cardReaderProvidedSwipeData(ECLCardReaderInterface eclCardReaderInterface, final ECLMagStripeOnlyData eclMagStripeCardData)
{
displayMessage("Track1 data: " + eclMagStripeCardData.getEncryptedTrack1Data(), false);
displayMessage("Track2 data: " + eclMagStripeCardData.getEncryptedTrack2Data(), false);
displayMessageInProgressView("First Name: " + eclMagStripeCardData.getFirstName(), false);
displayMessageInProgressView("Last Name: " + eclMagStripeCardData.getLastName(), false);
displayMessageInProgressView("Masked Pin: " + eclMagStripeCardData.getMaskedPan(), false);
displayMessageInProgressView("KSN: " + eclMagStripeCardData.getKsn(), false);
displayMessageInProgressView("Card Type: " + eclMagStripeCardData.getCardType(), false);
displayMessageInProgressView("Expiration Date: " + eclMagStripeCardData.getExpirationDate(), false);
}
Objective-C
You need to set up a delegate to implement ECLCardReaderRetrieveCardDataDelegate
and pass it to retrieveCardData
function of card reader protocol. The card data will be available in delegate’s providedMagStripeCardData
call back.
// set card entry types to swipe and contactless
ECLCardEntryType cardEntryTypes = ECLCardEntryType_MagneticStripeSwipe;
// set card entry type to manual keyed
ECLCardEntryType cardEntryTypes = ECLCardEntryType_ManuallyEntered;
[cardReader retrieveCardData:delegate usingCardEntries:cardEntryTypes];
+ (void)cardReaderRetrieveCardData:(id<ECLCardReaderProtocol>)cardReader providedMagStripeCardData:(ECLMagStripeCardData *)data {
[NSString stringWithFormat:@"Track 1 data: %@\n",[data encryptedTrack1Data]];
[NSString stringWithFormat:@"Track 2 data: %@\n",[data encryptedTrack2Data]];
[NSString stringWithFormat:@"Combine track data: %@\n",[data encryptedCombineTrackData]];
[NSString stringWithFormat:@"Masked PAN: %@\n",[data maskedPan]];
[NSString stringWithFormat:@"Cardholder First name : %@\n",[data firstName]];
[NSString stringWithFormat:@"Cardholder Last name : %@\n",[data lastName]];
[NSString stringWithFormat:@"Service Code : %@\n",[data serviceCode]];
[NSString stringWithFormat:@"Expiration Date : %@\n",[data expirationDate]];
}
C#
The card data is returned in a CardData
object.
public class CardData
{
public string lastName { get; set; }
public string expirationDate { get; set; }
public string encryptedTrack2Data { get; set; }
public string firstName { get; set; }
public string ksn { get; set; }
public string encryptedTrack1Data { get; set; }
public string fallback { get; set; }
public string encryptedCombineTrack1Data { get; set; }
public string maskedPan { get; set; }
public string source { get; set; }
public string formatCode { get; set; }
public string serviceCode { get; set; }
public string paymentType { get; set; }
public string pinKsn { get; set; }
public string encryptedPin { get; set; }
public string accountType { get; set; }
public string tlvData { get; set; }
public string processingCode { get; set; }
public string macValue { get; set; }
public string pinBlock { get; set; }
}
/* Delegate to handle results */
public void MyCardReadComplete(CardReadResults crr)
{
CardData cd = crr.CardData;
if (null != cd)
{
/* handle card read */
}
}
...
/* Setup CardReadArguments */
String [] entryTypes = new String[1];
entryTypes[0] = "SWIPE";
CardReadArgs args = new CardReadArgs();
args.retrievalModes = entryTypes;
/* Kick off the card read */
m_CWS.StartCardRead(args, MyNotifyCWSEvent, MyCardReadComplete);