> ## Documentation Index
> Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# View PIN

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.

<Info>
  <ul>
    <li>This feature is PCI-DSS compliant; hence, there is no risk of exposing sensitive confidential information.</li>
    <li>A cardholder can view PIN only for cards with an `INITIAL` or `ACTIVE` card version status.</li>
  </ul>
</Info>

## 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.

<div style={{marginLeft: '40px'}}>
  <strong>Related Endpoint</strong>: [Request PIN Control Access Token](https://nextgen-docs.enfuce.com/api/cards/post-card/create-pin-control-access-token)
</div>

```
curl --location "{{host}}/issuer/v1/cards/{{cardId}}/pinControl" \
--header "Content-Type: application/json" \
--header "Authorization: ••••••" \
--data "{
  \"scope\": \"VIEW_PIN\",
  \"sequenceNumber\": 1
}"

```

<Note>
  <ul>
    <li>In this request, you can specify the `sequenceNumber`. If no value is specified, the latest card version is used.</li>
    <li>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.</li>
  </ul>
</Note>

3. 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.

<img src="https://mintcdn.com/preview-docs/2Ueu8Wiqtu_soOb7/images/PIN-Retrieval.png?fit=max&auto=format&n=2Ueu8Wiqtu_soOb7&q=85&s=7caf4898807d85c2971549c8b9a175ea" alt="PIN Retrieval Endpoint Response" width="1280" height="489" data-path="images/PIN-Retrieval.png" />

4. The cardholder accesses either the `pinURL` or the `pinFrameURL`, based on where they are viewing the PIN.

<Note>The ID is valid for 30 seconds. The cardholder must access the appropriate URL within these 30 seconds to retrieve the HTML snapshot.</Note>

5. Another API request is sent to retrieve the card data in an HTML snapshot:

<div style={{marginLeft: '40px'}}>
  <ul>
    <li><strong>Mobile applications</strong>: Mobile application retrieves the HTML snapshot by any of the following ways:</li>

    <div style={{marginLeft: '30px'}}>
      <Accordion title="GET Request to `pinURL`">
        A GET request is sent to the `pinURL`, including the previously returned `id` in a query parameter titled `pinControlId`.

        ```
        curl --location "{{pinUrl}}?pinControlId={{id}"

        ```
      </Accordion>

      <Accordion title="POST Request to `pinURL`">
        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:

        <AccordionGroup>
          <Accordion title="Form Field">
            ```
            curl --location "{{pinUrl}}" \
            --header "Content-Type: application/x-www-form-urlencoded" \
            --data-urlencode "pinControlId={{id}}"
            ```
          </Accordion>

          <Accordion title="Query Parameter">
            ```
            curl --location --request POST "{{pinUrl}}?pinControlId={{id}}"
            ```
          </Accordion>

          <Accordion title="JSON Payload">
            ```
            curl --location "{{pinUrl}}" \
            --header "Content-Type: application/json" \
            --data '{
                "pinControlId": "{{id}}"
            }'            
            ```
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </div>

    <li><strong>Web applications</strong>: 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.</li>

    ```
    iframe.addEventListener('load', () => { 
      iframe.contentWindow.postMessage({operation: 'view-pin', id}, pinFrameUrl);
    })

    ```

    <Note>The API request fails if the `id` is incorrect.</Note>
  </ul>
</div>

6. 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`.

<div style={{marginLeft: '30px'}}>
  Here is a sample callback:

  ```
  window.android_handler.view_pin_success()
  ```
</div>

* **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.

<div style={{marginLeft: '30px'}}>
  Here is a sample callback:

  ```
  window.webkit.messageHandlers.ios_handler.postMessage({
      event: 'view_pin_success'
  });
  ```
</div>

<Info>On successful retrieval of PIN, the `view_pin_success` message is sent. If the operation failed, the `view_pin_error` message is sent.</Info>

### 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:

```
iframe.contentWindow.postMessage({operation: 'view_pin_success'}, targetOrigin);
```