Skip to main content

Handle PIN Entry

Some transactions require the cardholder to enter a PIN. Unlike signature capture, the SDK draws its own native PIN pad UI — you don't build this screen yourself. Your app is still responsible for getting out of the way: any dialog or overlay your app is showing (e.g. the "tap your card" dialog) must be hidden while the native PIN pad is on screen, or the PIN pad will be drawn behind it.

onTransactionUIEvent fires with these SDK constants (my.com.softspace.reader.TransactionCodes.TransactionUIEvent) during PIN entry:

ConstantMeaning
EVENT_ENTER_PINThe native PIN pad is about to be shown — hide your own UI now.
EVENT_PIN_ENTEREDThe cardholder finished entering their PIN — safe to restore your UI.
EVENT_PIN_TIMEOUTPIN entry timed out — safe to restore your UI.
EVENT_CANCEL_PINThe cardholder cancelled PIN entry — safe to restore your UI.
EVENT_PIN_BYPASSPIN entry was bypassed for this transaction. No UI action needed.
EVENT_CARD_READ_OK_REMOVE_CARDThe card was read successfully and can be removed. Informational — update any status text, no dialog changes needed.

Also see Capture Signature for the other onTransactionUIEvent case your app must handle, and Flow Overview for where this fits in the overall sequence.

Sample Handling​

@Override
public void onTransactionUIEvent(int event) {
    switch (event) {
        case TransactionUIEvent.EVENT_ENTER_PIN:
            onPinRequired(true);
            break;
        case TransactionUIEvent.EVENT_PIN_ENTERED:
        case TransactionUIEvent.EVENT_PIN_TIMEOUT:
        case TransactionUIEvent.EVENT_CANCEL_PIN:
            onPinRequired(false);
            break;
        default:
            writeLog("onTransactionUIEvent: Unhandled event (" + event + ")");
            break;
    }
}

private void onPinRequired(boolean requiresPin) {
    if (requiresPin) {
        tapCardDialog.hide();   // don't dismiss() — you'll want to show() it again
    } else {
        tapCardDialog.show();
    }
}