Prompt PIN Entry (On Demand)

This method directs the card reader to request a PIN from the cardholder.

note

This method requires a valid connected card reader.

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
startPinEntryOnCardReader
requestId
string | required
Transaction Request ID
targetType
string | required
cardReader
parameters
JSONObject | required
All relevant parameters to initiate a PIN entry prompt.
maskedPan
string | required
Masked Card Number

Response

PropertyDescription
requestId
string
Transaction Request ID
As specified in the request.
statusDetails
string
Request Status
data
JSONObject
Object holding various responses.
pinData
JSONObject
PIN Data
Object containing KSN, PIN and encryption method.
ksn
string
Key Serial Number
pin
string
Masked Card Number
encryptionMethod
string
Encryption Method

Example

Request
{
  "method" : "startPinEntryOnCardReader",
  "requestId" : "1669463288",
  "targetType" : "cardReader",
  "version" : "1.0",
  "parameters" : {
    "maskedPan" : "******"
  }
}

Later…

{
  "method" : "getCommandStatusOnCardReader",
  "requestId" : "1669463292",
  "targetType" : "cardReader",
  "version" : "1.0",
  "parameters" : {
    "id" : "1669463288"
  }
}
Response
{
  "requestId" : "1669463288",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "cardReaderCommand" : {
      "eventQueue" : [ ],
      "id" : "1669463288",
      "completed" : false
    }
  }
}

Later…

{
  "requestId" : "1669463292",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "cardReaderCommand" : {
      "eventQueue" : [ {
        "timeStamp" : "1477519715293",
        "statusDetails" : "PIN_ENTRY_COMPLETED"
      } ],
      "id" : "1669463288",
      "pinData" : {
        "ksn" : "******",
        "pin" : "******",
        "encryptionMethod" : "DUKPT"
      },
      "completed" : true
    }
  }
}

Java

ECLMagStripeCardData cardData = new ECLMagStripeCardData(ECLCardEntryType.UNKNOWN, null, null, ECLTriState.UNKNOWN);

String maskedPan = commerceAccount.getCardReader().getLastProvidedSwipedData().getMaskedPan();
cardData.setMaskedPan(maskedPan);

cardReaderInterface.retrievePin(new ECLCardReaderRetrievePinListener()
{
     @Override
     public void cardReaderProvidedPin(ECLCardReaderInterface cardReader,  ECLCardReaderPin pinResult)
     {
          /* Use pinResult */
     }

     @Override
     public void cardReaderRetrievePinError(ECLCardReaderInterface cardReader, ECCError error)
     {
           /* Handle error */
     }

     @Override
     public void cardReaderProgress(ECLCardReaderInterface cardReader, ECLTransactionProgress progress)
     {
           logger.info("cardReaderProgress " + progress.toString());
     }
}, cardData);

/* ECLCardReaderPin has the following public methods */
public class ECLCardReaderPin
{
    public ECLEncryptionMethod getEncryptionMethod();
    public String getKsn();
    public String getPin();
}

Objective-C

// Card data from last on-demand card read
ECLMagStripeCardData *prevCardData;

// Card reader instance
id<ECLCardReaderProtocol> cardReader;

[cardReader retrievePin:self forCardData:prevCardData];

// Implement ECLCardReaderRetrievePinDelegate callback methods
+ (void)cardReaderRetrievePin:(id<ECLCardReaderProtocol>)cardReader providedPin:(ECLCardReaderPin *)pinResult 
{
    /* Use pinResult */
}
     
+ (void)cardReaderRetrievePin:(id<ECLCardReaderProtocol>)cardReader error:(NSError *)error 
{
    /* Handle error */
}

+ (void)cardReaderRetrievePin:(id<ECLCardReaderProtocol>)cardReader progress:(ECLTransactionProgress)progress 
{
    [self addStatusString:[NSString stringWithFormat:@"%@\n",[ECLDebugDescriptions descriptionOfTransactionProgress:progress]]];
}


// ECLCardReaderPin has the following properties
@interface ECLCardReaderPin : NSObject

@property (readonly)ECLCardReaderPinEncryptionMethod encryptionMethod;
@property (readonly)NSString *ksn;
@property (readonly)NSString *pin;

C#

/* Asynchronous */
        m_CWS.StartPinEntry(myMaskedPan, MyNotifyCWSEvent, MyPinEntryComplete);

/* Synchronous */
        PinEntryResults per = m_CWS.PinEntry(myMaskedPan, null);
         MyPinEntryComplete(per);

/* Do something with the pin data */

        public void MyPinEntryComplete(PinEntryResults per)
        {
            Log("----------- PinEntry Complete ------------");
            PinData pd = per.PinData;
            if (null != pd)
            {
                Log(String.Format("KSN {0}", pd.ksn));
                Log(String.Format("Pin {0}", pd.pin));
                Log(String.Format("EncryptionMethod {0}", pd.encryptionMethod));