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

PropertyDescription
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

PropertyDescription
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);