Skip to content

Set PIN

Set PIN allows the customer to choose the PIN (Personal Identification Number) of the card. This can be done safely and conveniently through mobile or web app. The set PIN functionality improves the customers experience by allowing the customer to choose the PIN rather than being forced to remember a randomly generated one. It also reduces issuer cost by making PIN letters delivered by mail redundant.

Key benefits of the service:

  • Great customer experience by allowing users to choose the PIN for their card rather than memorizing a randomly generated one.
  • Easy and fast implementation with a well designed API enables offering a valuable service to customers with moderate development effort.
  • 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.
  • Enables a fully digital PIN process that besides great customer experience and reduces issuer cost by making PIN letters redundant.

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

The service is designed to avoid exposure of sensitive, PCI categorized data to the web/app back-end, therefore the PIN data is encrypted from the user’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 impact on the this functionality:

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

Enfuce recommends the following guidelines for issuer application development:

  • The app on the customer device and the related back-end should ensure that the user is strongly authenticated (SCA) before being able to set the PIN data.
  • The RSA keys need to be generated by the device and it should be ensured that the back-end is not able to de-crypt the PIN encryption key nor the encrypted PIN block.
  • The app on the customer device shall not save the PIN that the 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.
  • The app should instruct the user not to set too weak PIN code
    • Strong PIN code contains a combination of numbers and doesn’t include easily guessable patterns

Please refer to PIN Control API documentation for more technical details.