Skip to content

Set PIN

The ‘set PIN’ functionality allows your customer to choose their PIN (Personal Identification Number) for their card. This can be done safely and conveniently through a mobile or web app. This improves your customer’s experience by allowing them to choose their own PIN rather than being forced to remember a randomly generated one. It also reduces your costs by making PIN letters delivered by mail redundant.

Key benefits of ‘set PIN’:

  • Improved customer experience by allowing them to choose their own PIN rather than memorising a randomly generated one.
  • Enables a fully digital PIN process that besides great customer experience reduces your costs by making PIN letters redundant.
  • Easy and fast implementation with a well-designed API.
  • Secure and compliant. Designed to avoid exposure of sensitive data to the web/app back-end. The functionality is developed, assessed, and certified according to the latest compliance requirements.

Set PIN process

The Set PIN process has multiple steps to ensure security:

  1. The process starts with card creation. In the card creation request, you should indicate if the card will have a PIN set by your customer or a random PIN.
    1. pinStatus should be set to “W” when your customer sets the PIN. By defining the PIN status as “W”, the card will not be produced until the PIN has been set. Enfuce has no time limit for the wait, i.e. if PIN is not received, the card will remain in a “waiting for PIN” status and will never be produced.
      1. If your customer wishes to revert to a random PIN before setting a self-selected PIN (i.e. pinStatus is still “W”), this can be done by setting the pinStatus to “D”. After the change, the card will be embossed with random PIN in the next run.
  2. After the card is created, you will need the plasticId of the newly created card. The plasticId is specific to each sequence of the card (e.g. if there are several with the same card number but different expiration dates). you should choose the plasticId that has "status": "INACTIVE" (=card has not yet been produced)
    1. /card/v3/{id}/plastic
  3. The plasticId is needed when requesting the controlId. The controlId will be the key during the set PIN process to identify what card the PIN should be linked to.
    1. /pincontrol/v2/plastic/{plasticId}
  4. The successful response from this endpoint returns an ID and a pinURL a. Note the ID is valid for 30 seconds which is the deadline for your customer’s device to make the POST call to retrieve the HTML snapshot.
  5. your customer device (app/web interface) is instructed to access the returned URL to be able to set the PIN.
  6. Your customer’s device retrieves an HTML snapshot by executing a POST call to the pinURL with the content of the id in a form field named controlId. a.<URL_GOES_HERE>?controlId==<ID_GOES_HERE> b. The request will fail if the token is not valid.
  7. Returned HTML contains a JavaScript which will handle input of customer-selected PIN, encryption and transfer of encrypted PIN to Enfuce.
    a. A public key pair is generated on the device.
    b. The public key is sent to Enfuce.
  8. Enfuce will generate an encryption key (TZPK) for the PIN that is sent to the device encrypted with the public key.
  9. Your customer enters a new PIN in web form and after submitting JavaScript will encrypt your customer’s chosen PIN with the TZPK key.
  10. Enfuce links the PIN with the correct card and triggers the card to be included in the next embossing run. It should be noted that the newly set PIN can be viewed through the API only after the embossing run (daily run in production at 03:00 UTC, and once per hour in the test environment).
  11. Your customer receives a card with a set PIN
  12. To check afterwards if a specific card has a set PIN or a random PIN, pinStatus can be used. a. pinStatus : "D" → Random PIN has been used for card b. pinStatus : "S" → Set PIN has been used for card

PCI and security considerations

This functionality is designed to avoid exposure of sensitive, PCI-categorised data to the web/app back-end, therefore the PIN data is encrypted from your customer’s device to the service endpoint. The functionality is developed and assessed for PCI DSS. PCI DSS regulations are detailed, but highlighting a few that have an impact on this functionality:

  • PIN data remains encrypted in transport.
  • The software is code-reviewed.
  • The publicly exposed endpoint is protected by a web application firewall.

We recommend the following guidelines for issuer application development:

  • The app on your customer’s device and the related back-end should ensure that your customer is strongly authenticated (SCA) before setting the PIN data.
  • The RSA keys need to be generated by the device and it needs to be ensured that the back-end is not able to decrypt the PIN encryption key or the encrypted PIN block.
  • The app on your customer’s device shall not save the PIN that your customer enters. After the PIN has successfully been set it can be viewed through View PIN API.
  • The app developers need to take necessary precautions to stop other apps or processes from accessing or interacting with the set PIN process.
  • The app developers need to ensure that the communication between the app and the related back-end is done in an authenticated and encrypted session.

Have a look at the PIN Control API documentation for more technical details.