Prompt PIN Entry

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