What can we help you with?

Offline PINs


What is offline vs. online PIN?

When a PIN is entered at the terminal, it needs to be checked against a stored PIN value. That PIN can be stored on the card (offline), or with the card issuer (online). 

The order in which these values are checked, if at all, is determined by each merchant’s payment gateway and terminal configurations. Often those configurations are mandated by the region the merchant operates in - Canada and Mexico are two examples of regions where offline PIN is preferred, whereas the US operates with online PIN.

To ensure a good customer experience, programs operating in offline PIN regions should implement PIN setting at card creation time so that the PIN can be encoded onto the card. If the PIN is not set at the time of manufacture, the customer will not be able to use the card without first going in-person to a merchant; the customer may have to set the PIN manually at a point-of-sale (POS) terminal.


Configure the card with the customer’s chosen PIN in a way that transactions will work on the first try, without having to go through the three-step retry and scripting process.

Current limitations of offline PIN

  • Offline PINs are validated between the chip and terminal instead of being sent for online authentication to the issuer host system.

  • Offline PINs must be set prior to the card’s first use in order for the first authorization attempt to succeed.

  • Resetting a PIN at the point of sale requires a three-step process with a compatible merchant. The customer enters their PIN and sees a decline/rejection message three times in a row, then the merchant’s payment terminal falls back to an alternate card verification method (CVM). Once the transaction is approved with the alternate CVM, the accepting terminal will request to encode the new PIN that’s received from the issuing processor (Marqeta). At this point, the PIN that’s embedded in the card will be updated to the new, user-provided PIN.


  • Customer performs PIN set online after card creation request and before fulfillment request
    • Requires customer to incorporate a PIN setting mechanism as part of card request
    • First transaction at POS with proper PIN will be successful


If there is a requirement to support offline PIN for your programme, you should address some additional considerations during the onboarding to Marqeta.

Network setup

Ensuring support for offline PIN requires configuring the relevant Cardholder Verification Method (CVM) added to the list of allowed methods to ensure the correct order of verification methods. You should speak to your network representative who can advise further on the required settings for offline PIN support.

Card product setup

To support offline PIN, the "enable_offline_PIN" field must be set to "true" within your card product setup. With this setting turned on, Marqeta will include the ‘PIN block’ that the card fulfilment provider needs to encode the PIN onto the card.

  "config": {
    "fulfillment": {
      "enable_offline_PIN": true

You can refer to https://www.marqeta.com/docs/api-explorer/#/cardproducts/getCardproducts for more information.

PIN setting methods

When creating a new card, as default no PIN is set. There are several different implementations that a programme can implement for PIN setting each with unique customer experience.

During card creation via API

The most common method of setting a PIN is at the point of card creation. After card creation, the PIN is immediately set, this means that the fulfilment provider receives an encrypted version of the chosen PIN and securely programs the chip with the cardholder's PIN. This method ensures the offline and online PIN are in sync, and the cardholder can use it on any terminal as soon as it arrives. Setting a PIN at the point of card creation can only be achieved via the API, Marqeta’s widgets enforce that the card must be activated prior to setting a PIN whereas API does not.

Implementation steps

  1. POST request to /cardproducts to create a physical card product with offline PIN enabled (if required) as described above.
  2. POST request to /cards to create a card using user token and card product token from previous step.
  3. POST request to /pins/controltoken to create a control token via with request body of {"card_token": "string"}. API endpoint will provide control token in response {"control_token": "string"}
  4. PUT request to /pins with request body of {"control_token": "string","PIN": "string"} which will set the PIN of the card.
  5. The card is sent to fulfilment provider with an encrypted PIN block of the above PIN value which will be programmed into the chip of the card. Note: The above steps must be completed prior to the card being sent to fulfilment provider if there is to be a PIN set on the chip. If these are not completed the card will be sent to the provider with no PIN.

 Bulk card ordering

The steps for setting PIN is the same for bulk card orders with two differences:

  • The bulk order must be created first with a quantity/allocation of zero. Cards will then be added to the bulk order after-the-fact.
  • As cards are created, you will also pass the bulk card order’s token/ID with the POST request to /cards. This attribution of the card to this bulk order cannot be done after the card is created.

PIN reset

Changing a card holder's PIN via Marqeta API or widgets updates the online PIN. This forces the offline PIN and online PIN out of sync meaning that if you tried your new PIN, for example, on an aeroplane, this would be declined as the card still has reference to the old PIN. Marqeta sets a flag each time a cardholder changes their PIN; this flag remains set until Marqeta next interacts with that card during an online PIN authorization attempt, at which point the Marqeta platform resyncs the PINs.

Typically, customers will go to a card terminal in order to exceed the maximum offline PIN attempts (usually set to 3), which will then force the terminal to check the online PIN after 3rd invalid PIN attempt. Marqeta can then update the offline PIN and resets the offline PIN counters.

Implementation Steps

Resetting PIN at the POS

Marqeta can only interact with the chip when the transaction comes “online”, in an offline PIN scenario the PIN validation is completed offline, therefore, Marqeta will only see the transaction after the final PIN attempt (most often set to 3). The below steps are the alternative way to trigger this. The below steps will depend on how many invalid PIN attempts the customer has attempted before hand:

  1. POST request to /pins/controltoken to create a control token with request body of {"card_token": "string"}. API endpoint will provide control token in response {"control_token": "string"}
  2. PUT request to /pins with request body of {"control_token": "string","PIN": "string"} which will set the PIN of the card.
  3. The customer enters their new PIN. If PIN counter = 3, Customer will receive an invalid PIN message, PIN counter will be decreased
  4. The customer enters their new PIN again. If PIN counter = 2, Customer will receive an invalid PIN message, PIN counter will be decreased
  5. The customer enters their new PIN again. If PIN counter = 1, Customer will receive an invalid PIN message (final attempt), the transaction then comes online to Marqeta, if the customer has recently set a new PIN, the transaction should be approved (without PIN) and will use the next available CVM (usually signature) and Marqeta will write the PIN down to the chip and reset the counters. Note the transaction must be approved on this attempt for the script to successfully run.
  6. The following transaction the customer completes should now prompt for a PIN which will now be the offline PIN (if in an offline PIN environment).


Marqeta provides notification of PIN change to your programs webhook endpoint if subscribed to card action events (cardactions.*) within webhook configuration which the payload is as below:

  "cardactions": [
      "card_token": "**REMOVED**",
      "created_time": "2020-04-17T17:01:08Z",
      "state": "SUCCESS",
      "token": "**REMOVED**",
      "type": "PIN.changed",
      "user_token": "**REMOVED**"

PIN attempt limits

Online PIN

Marqeta’s online PIN allows for a limit of 3 invalid PIN attempts before a card will be suspended. When this occurs the card is suspended and awaits action from the client, this allows clients to investigate whether this is a genuine mistake or a fraudulent attempt. Once the client is happy that the customer's attempt was not fraudulent if required the PIN can be reset. The card can then be transitioned back to an ACTIVE state. By doing this the retry limits will be reset to 0 allowing the card to be fully functional once more.


Invalid Pin Attempt

"response" : {
  "code" : "1809",
  "memo" : "Invalid Pin"

Card transition to suspended due to PIN try limits

  "cards": [
      "fulfillment_status": "ORDERED",
      "last_four": "7890",
      "pan": "123456______7890",
      "PIN_is_set": true,
      "reason": "Pin Retry Limit Reached",
      "reason_code": "22",
      "state": "SUSPENDED",
      "token": "**REMOVED**",
      "type": "state.suspended",

Offline PIN

Like the online PIN, the offline PIN is usually set to 3 also however this is dependent on the client's chip profile. The offline PIN can only be changed or reset at transaction time when the chip is in connection with the terminal which allows updating of the chip values. As the offline PIN verification does not come online Marqeta would not be notified of PIN failures and would only become aware when the PIN retry limit has exceeded. When the PIN verification comes online Marqeta will look for a PIN reset if there is one will perform a PIN change as noted in this documentation to sync the PINs and the transaction would approve. However, no PIN set had occurred the transaction would be declined with PIN try limit exceeded. Customers would continue to experience this behaviour until the PIN had been reset and the PIN script had been successfully run.

Implementation Steps

  1. The customer enters incorrect PIN, terminal states incorrect PIN customer if offered a retry.
  2. The customer enters incorrect PIN for a second time, terminal states incorrect PIN customer if offered a retry.
  3. Terminal states final attempt, the customer enters incorrect PIN for the third time, the transaction comes online to Marqeta and gets declined as there is no pending PIN reset, terminal states that the Card is now blocked and the transaction is cancelled. Marqeta display Pin try limit exceeded on the transaction.
  4. POST request to /pins/controltoken to create a control token with request body of {"card_token": "string"}. API endpoint will provide control token in response {"control_token": "string"}
  5. PUT request to /pins with request body of {"control_token": "string","PIN": "string"} which will set the PIN of the card.
  6. The customer enter card into the POS and the transaction should be approved without PIN utilizing the next CVM in the list (usually signature). If approved Marqeta will run the PIN script which will sync the PIN between Marqeta and the chip and unblock the card resetting the PIN counters. The card is now unblocked and ready to be used again.


"response" : {
  "code" : "1872",
  "memo": "Pin try limit exceeded"


Thanks for the feedback
Thanks for the feedback
Was this article helpful?

We've recieved your feedback.

Contact Developer Support
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.