Skip to main content
This capability enables your cardholders to safely view the card PIN on mobile or web applications. Viewing PIN on the issuer provided channel reduces significant cost incurred on delivering PIN via mail or courier services.
  • This feature is PCI-DSS compliant; hence, there is no risk of exposing sensitive confidential information.
  • A cardholder can view PIN only for cards with an INITIAL or ACTIVE card version status.

​
Viewing PIN | Workflow

  1. A cardholder completes Strong Customer Authentication (SCA) and initiates a request in the mobile/web application to view PIN.
  2. Your system sends an API request to Enfuce to generate a unique temporary ID and two URLs – one for the mobile view and the other one is for the web view.
  • In this request, you can specify the sequenceNumber. If no value is specified, the latest card version is used.
  • We do not perform additional validation, except the cardId. Hence, if the cardId is invalid, the request fails. If you want to check whether the card is eligible for payments, you must send additional API requests to verify the card status and its balance.
  1. In the endpoint response, a unique ID and two URLs are returned — pinURL is for viewing the PIN on mobile devices and pinFrameURL is for viewing the PIN on web.
PIN Retrieval Endpoint Response
  1. The cardholder accesses either the pinURL or the pinFrameURL, based on where they are viewing the PIN.
The ID is valid for 30 seconds. The cardholder must access the appropriate URL within these 30 seconds to retrieve the HTML snapshot.
  1. Another API request is sent to retrieve the card data in an HTML snapshot:
  • Mobile applications: Mobile application retrieves the HTML snapshot by any of the following ways:
    • A GET request is sent to the pinURL, including the previously returned id in a query parameter titled pinControlId.
    A ‘POST’ request is sent to the pinURL, including the previously returned id in a parameter titled pinControlId. The request can be sent in any of the following ways:
  • Web applications: The browser opens iframe to pinUrl. Then the parent page sends a window.postMessage() to the iframe. The posted message object includes operation: view-pin and id field.
    • The API request fails if the id is incorrect.
  1. An HTML snapshot is returned with the PIN included. The HTML includes a Javascript that manages the retrieval and encryption of PIN:
    1. A public key is generated on the device.
    2. The public key is sent to Enfuce.
    3. The PIN is encrypted with the public key and returned to the device.
    4. Javascript decrypts the PIN and includes it in the HTML snapshot.

​
Page Callbacks

You can implement callback both for the mobile and the web applications:

​
Callbacks for Mobile Devices

  • Android Devices: The javascript interface name is android_handler.
Here is a sample callback:
  • iOS Devices: The message handler name is ios_handler. The posted message body includes the event parameter containing the callback name and might also contain the pin_valid-field.
Here is a sample callback:
On successful retrieval of PIN, the view_pin_success message is sent. If the operation failed, the view_pin_error message is sent.

​
Callbacks for Web applications

The iframe returns the window.postMessage() events to the parent page; these events are the same as the ones sent in the mobile devices workflow and the format of the events is similar with the iOS workflow: