Skip to main content

Manage the card PIN

Physical cards have a PIN for chip-and-PIN payments and ATM withdrawals. An initial PIN is generated when the card is issued. Cardholders can view and change it with the Card SDK. There is no PIN mailer: the Card SDK is how cardholders see their PIN.

The PIN is only ever shown or entered inside the SDK's secure views. It never passes through your app's code or your backend.

Show the PIN​

PinRevealView shows the card's current PIN for 10 seconds, then hides it again. The session needs the PIN_REVEAL operation. Showing the PIN must be enabled on your Card Program, and can be limited to a number of times per day.

Like SecureCardView, the view doesn't need a session. Create it right away, then call card.revealPin() once you have a SecureCard:

import co.openfabric.securecard.view.PinRevealView

val pinRevealView = PinRevealView(context)
container.addView(pinRevealView)

card.revealPin(
view = pinRevealView,
callback = object : SecureCardCallback<Unit> {
override fun onSuccess(result: Unit) { /* The PIN is showing, counting down */ }
override fun onError(error: OpenFabricError) { /* ... */ }
},
)

To show the PIN again, call revealPin() again. Each reveal runs your authGate and counts towards the daily limit.

Change the PIN​

PinInputView asks the cardholder for their current PIN, a new PIN, and the new PIN again to confirm. The PIN length and rules are set by your Card Program. PINs are entered on the SDK's own secure keypad, never through the system keyboard or your page. The session needs the PIN_CHANGE operation.

Call card.startPinChange() to prepare the view. The PIN is changed when the cardholder has completed all three entries and taps the view's submit button:

import co.openfabric.securecard.view.PinInputView

val pinInputView = PinInputView(context)
container.addView(pinInputView)

card.startPinChange(
view = pinInputView,
callback = object : SecureCardCallback<Unit> {
override fun onSuccess(result: Unit) { /* PIN changed */ }
override fun onError(error: OpenFabricError) {
// Called for every failed attempt, e.g. PIN_VERIFICATION_FAILED
// when the current PIN is wrong, or PIN_RETRY_EXCEEDED when the PIN is locked
}
},
)

After a failed attempt, such as a wrong current PIN (PIN_VERIFICATION_FAILED) or a PIN that is too easy to guess (PIN_WEAK), the view clears the entries so the cardholder can try again. On Android, every failed attempt is reported to onError. On the web, failures the cardholder can fix go to pinInput.onError, and the promise only rejects when the change can't go on, for example when the PIN is locked (PIN_RETRY_EXCEEDED).

If the error is PIN_CHANGE_OUTCOME_UNKNOWN, it isn't known whether the PIN was changed. The view doesn't retry: ask the cardholder to try the new PIN first.

If you configured an authGate, it runs when the cardholder submits the PIN change, so a declined check never loses what they typed.

Style the PIN views​

You can match the PIN views to your app's branding. Leave a style unset to use the SDK's defaults. The size of the PIN in PinRevealView is kept between 16 and 96.

pinRevealView.style = PinRevealViewStyle(
pin = PinRevealViewStyle.TextStyle(fontFamily = myTypeface, fontSizeSp = 32f, textColor = Color.BLACK),
label = PinRevealViewStyle.TextStyle(fontFamily = myTypeface, fontSizeSp = 14f, textColor = Color.GRAY),
countdown = PinRevealViewStyle.TextStyle(fontFamily = myTypeface, fontSizeSp = 12f, textColor = Color.GRAY),
)

pinInputView.style = PinInputViewStyle(accentColor = getColor(R.color.brand))

PIN lock​

If the wrong PIN is entered too many times at a terminal, at an ATM or in the PIN change view, the PIN is locked. You receive a v1:card:pin:locked notification, and SDK calls return PIN_RETRY_EXCEEDED.

A locked PIN can't be changed. You can unlock it from your backend with the Unlock PIN API, for example after verifying the cardholder through your customer support. Once the PIN is unlocked, you receive a v1:card:pin:unlocked notification. See Lifecycle notifications.