Encrypted Card Read (On Demand)

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.

error_outline
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

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

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