About Personal Identification Numbers
A Personal Identification Number (PIN) is an optional four-digit number combination used to verify the identity of your cardholder. Cardholders can use their PIN to transact with their card, to authenticate their identity when communicating with you, or to access their account information. A PIN is similar to a password, and should be kept secret to prevent unauthorized access to your customers' accounts and information.
Some countries and/or card network schemes—including the EMV "chip and PIN" cards used in Europe and on the debit networks within the US—require a PIN in order to make certain types of transactions. You can also choose to enable the PIN feature, even when it is not required. To enable or configure this feature for your program, contact your Marqeta representative.
PINs can be validated either online or offline:
-
An online PIN is entered by the cardholder, then transmitted along with the card details to the issuer (Marqeta) via the merchant acquirer for authentication. The PIN is not stored on the card. The Marqeta platform receives the authentication request from the card network, validates the PIN, then confirms to the merchant terminal where the card is inserted.
-
An offline PIN is entered by the cardholder, then transferred in encrypted form to the card’s integrated circuit (or "chip") where the PIN is stored. The chip uses its internal method to confirm the PIN to the merchant terminal where the card is inserted. In certain European markets and in Canada, offline PINs may be validated by the merchant terminal alone without connecting to the Marqeta platform if the merchant doesn’t have real-time connectivity.
Revealing or updating a cardholder’s PIN
Copy section link
Note
PIN Reveal functionality is not available by default, and must be explicitly activated for your program. Contact your Marqeta representative if you want to enable or disable PIN Reveal functionality for your program.If you are PCI-DSS compliant, you can reveal a cardholder’s PIN by sending a POST request to the /pins/reveal API endpoint.
Similarly, you can update a cardholder’s PIN by sending a PUT request to the /pins endpoint.
If you are not PCI certified, use Marqeta’s Javascript library (marqeta.js) to reveal card details to the cardholder and copy these values to the clipboard for later use. You can also use marqeta.js to view the cardholder’s PIN.
Learn more in the Revealing PIN Numbers guide, as well as in the Marqeta Dashboard Control Center guide.
Setting your program’s PIN retry limit value
Copy section link
A cardholder can make a configurable maximum number of unsuccessful PIN retries before hitting the limit and transitioning the card state to SUSPENDED via the Marqeta platform.
When a card is suspended, all POS and ATM authorizations are blocked.
Setting a retry limit is an added layer of security that helps reduce fraudulent activity because it prevents an attacker from making endless attempts to brute-force guess the PIN of a lost or stolen card.
You can set the PIN retry limit to any value you choose, or decide not to impose a limit for your program at all.
If you want to specify the maximum number of unsuccessful PIN retries that a cardholder can make before transitioning the card state to SUSPENDED, ask your Marqeta representative to modify the PIN retry limit for your program on your behalf.
Resetting the PIN retry counter of a locked-out card
Copy section link
A webhook is used to inform the cardholder that they have locked out their card by reaching its PIN retry limit.
This webhook behaves in the same way as a webhook for a suspended card.
You receive a state.suspended webhook with the reason "PIN try limit exceeded" (response code 1872).
After receiving this webhook, you could choose to display a message such as the following on the cardholder’s screen, "Your card is temporarily inactive due to an issue with your account.
Please contact Customer Support for assistance."
There are several scenarios where a card state can be transitioned from SUSPENDED to ACTIVE or TERMINATED via the API after the cardholder reaches the maximum number of unsuccessful PIN retries:
-
The cardholder confirms that fraud has occurred, and you reissue the card to them. This scenario typically occurs when the cardholder still possesses the physical card, but someone else has discovered their PAN. The PIN retry counter’s value is reset to zero so the cardholder can transact with the card like before. To resolve this scenario, see Reissuing a card after fraud has occurred.
-
The cardholder cannot remember their own PIN, and has decided to reset it, which would also reset the PIN retry counter’s value to zero. No fraud was committed in this scenario. You must transition the card state from
SUSPENDEDtoACTIVEso the cardholder can transact with the card like before. Transitioning the card state toACTIVEresets the PIN retry counter’s value to zero for the cardholder. To resolve this scenario, see Resetting the cardholder’s forgotten PIN. -
The cardholder had trouble remembering their own PIN. No fraud was committed in this scenario, and they do not want to change their PIN because they remember it now. You must transition the card state from
SUSPENDEDtoACTIVEso the cardholder can transact with the card like before. Transitioning the card state toACTIVEresets the PIN retry counter’s value to zero for the cardholder. This scenario also applies if you have enabled the PIN Reveal feature for your program and the cardholder uses your application to view their current PIN. To resolve this scenario, see Resetting the card’s PIN retry counter’s value to zero.
Note
Reaching the PIN retry limit value transitions the card state toSUSPENDED, but does not affect the associated account.
PIN retry flow
Copy section link
Below is a summary view of the PIN retry flow, along with the steps to follow for each of the scenarios previously described.
Reissuing a card after fraud has occurred (A)
Copy section link
-
Reissue the card by sending a
POSTrequest to the/cardsendpoint. The card’s retry limit is automatically reset to zero as part of reissuing the card. -
Have the cardholder choose a new PIN for their card via your application.
Resetting the cardholder’s forgotten PIN (B)
Copy section link
-
Reset the cardholder’s PIN to a new value via your application.
-
Transition the card to
ACTIVEby sending aPOSTrequest to the/cardtransitionsendpoint. Transitioning the card toACTIVEresets the PIN retry counter’s value to zero for the cardholder.
Resetting the card’s PIN retry counter’s value to zero (C)
Copy section link
-
Transition the card to
ACTIVEby sending aPOSTrequest to the/cardtransitionsendpoint. Transitioning the card toACTIVEresets the PIN retry counter’s value to zero for the cardholder.