Prompt PIN Entry (On Demand)

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

error_outline
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

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

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