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

# Set PIN

This capability enables your cardholders to specify a card PIN of their choice through the issuer-provided mobile or web applications. It also reduces the significant cost incurred in delivering PIN through mail or courier services. This also optimises the user experience as cardholders are empowered to choose a PIN of their preference.

<Info>The <strong>Set PIN</strong> function prohibits any exposure of sensitive data to the backend processes and is compliant with the latest security requirements. For more information, see [PCI and Security Compliance](##pci-compliance).</Info>

## Setting PIN | Supported Workflows

This section explains how PIN setting works during new card creation, reissue, and replacement.

## New Card Creation

When you are creating a new card via the [Create Card Endpoint](https://nextgen-docs.enfuce.com/api/cards/post-card/create-card), you can perform any of the following:

* `pinStatus` parameter set to `GENERATED`: This is the default value and it creates a random PIN for the new card.
* `pinStatus` parameter set to `WAITING`: If you specify this value, you can set the PIN later. Once you set the PIN, the PIN status is changed to `SET`.

<Note>The card cannot be included in the embossing file when the `pinStatus` is `WAITIING`; it is sent to the manufacturer for printing the plastic card only when the status is changed to `SET`.</Note>

### Card Reissue

When a card is reissued, by default, the PIN remains the same in the new version. However, You can modify this behaviour via the [Reissue Card Endpoint](https://nextgen-docs.enfuce.com/api/cards/post-card/reissue-card) > `pinStatus` parameter:

<ul>
  <li>Specify `GENERATED` to set a random PIN.</li>
  <li>Specify `WAITING` to manually set the PIN later.</li>
</ul>

### Card Replacement

When a card is replaced, by default, a random PIN is generated. You can modify this behaviour via the [Replace Card Endpoint](https://nextgen-docs.enfuce.com/api/cards/post-card/replace-card) — to set the PIN later, specify `WAITING` for the `pinStatus` parameter.

## Set PIN | Workflow

You can set PIN for the latest card version with an encrypted PIN block in ISO format 1. The PIN block is encrypted using a pre-shared double-length 3DES key. If the ZPK index is not specified, the first key is used, by default.

<Note>In a multi-application card, the multiple card applications included in the main application inherits the same PIN.</Note>

### Prerequisite

When you are creating a new card, via the [Create Card Endpoint](https://nextgen-docs.enfuce.com/api/cards/post-card/create-card), you can perform any of the following:

* `pinStatus` parameter set to `GENERATED`: This is the default value and it creates a random PIN for the new card.
* `pinStatus` parameter set to `WAITING`: If you specify this value, you can set the PIN later. Once you set the PIN, the PIN status is changed to `SET`.

<Note>
  <ul>
    <li>Unless the PIN is set, the card cannot be included in the embossing file for manufacturing the plastic card.</li>
    <li>After the `pinStatus` is set to `WAITING`, if the cardholder wants to generate a random PIN: send a request via the [Partially Update Card Endpoint](https://nextgen-docs.enfuce.com/api/cards/patch-card/partial-update-card) and set the `pinStatus` parameter to `GENERATED`.</li>
  </ul>
</Note>

### Step-by-Step Guidance

If the `pinStatus` was set to `WAITING`, the PIN can be set in the following process:

<Steps>
  <Steps>
    <Step title="First Step">
      The cardholder is successfully authenticated in the issuer-provided mobile or web application.
    </Step>

    <Step title="Second Step">
      The cardholder enters a PIN for their card.
      <Note>The PIN must meet the complexity requirements. The operation cannot be completed if the PIN is weak – a weak PIN is easy to guess; it includes simple sequences/consecutive or repeated digits, or common patterns. These PINs are blocked for security reasons. The exact list of weak PINs is not disclosed and is updated over time to counter security breaches.</Note>
    </Step>

    <Step title="Third Step">
      Javascript creates the PIN block for the PIN:

      1. Generates the PIN block in ISO Format 1.

         <strong>Sample Format</strong>:

         `<Format Version><PIN Length><PIN><Random HEX digits to fill 8 bytes>`

         <strong>Example</strong>:

         \`\`\`version = 1, PIN length = 4, PIN = 7856, random hex = 3CB5055865, PIN block = 1478563CB5055865 (hex, 8 bytes)\`\`

      2. Encrypts the clear PIN block using the pre-shared double-length 3DES ZPK (Zone PIN Key).

      3. Converts the encrypted PIN block to a hexadecimal string (uppercase).
    </Step>

    <Step title="Fourth Step">
      The issuer sends a request to the [Set PIN Endpoint](https://nextgen-docs.enfuce.com/api/pin/set-pin).
    </Step>

    <Step title="Fifth Step">
      If the request is valid, the endpoint returns `200` HTTP response code — the encrypted PIN is set. Enfuce associates the encrypted PIN with the specific card ID and includes the card in the next embossing file for printing the plastic card.
    </Step>

    <Step title="Sixth Step">
      The issuer communicates the response to the cardholder.
    </Step>

    <Step title="Seventh Step">
      The cardholder receives the plastic card with the PIN set.
    </Step>
  </Steps>
</Steps>

<Note>To check whether a card PIN has been manually set by the Set PIN workflow or a random PIN is generated, send a request to the [Get Card Endpoint](https://nextgen-docs.enfuce.com/api/cards/get-card/get-card):<ul><li> If the PIN is manually set, the `pinStatus` parameter specifies `SET`.</li><li> If the PIN is randomly generated, the `pinStatus` parameter specifies `GENERATED`.</li></ul></Note>

## PCI Compliance

The **Set PIN** feature is designed in such a manner that it does not expose any sensitive, PCI-categorised data to the backend processes; this is compliant with the PCI DSS regulations and the following list highlights a few pointers of compliance:

* The PIN data is encrypted during transmission.
* The software is code reviewed and quality checks are ensured.
* The [Set PIN Endpoint](https://nextgen-docs.enfuce.com/api/pin/set-pin) is protected by a web application firewall.

### Enfuce Recommendations | Guidelines for Issuers

* Ensure that the cardholder accessing either the mobile/web application must be authenticated via the Strong Customer Authentication (SCA) process, before setting the PIN of their choice.
* Your application must not save the PIN that the cardholder enters.
* Ensure that other third-party applications interfacing with your application does not interfere in the set PIN workflow. Also, confirm that the interactions between your application frontend and the backend is done in an authenticated and encrypted session.