Set PIN

This capability enables your cardholders to specify a card PIN of their choice through the issuer-provided mobile or web application, rather than being forced to remember a randomly generated one. It also removes the significant cost of delivering PIN through mail or courier services. Key benefits of the service:

A great customer experience — cardholders choose their own PIN instead of memorising a randomly generated one, with no call-centre step or reissue.
Lower support costs
Your back-end stays out of PCI scope. The clear PIN is entered and encrypted only on the cardholder’s own device; no PIN material, encrypted or otherwise, is ever exposed to your web/app back-end. The functionality is developed, assessed, and certified for PCI DSS.

New Card Creation

Before a PIN can be set, indicate in the card creation request whether the card should get a random PIN or wait for the customer to choose one. Via the Create Card Endpoint:

pinStatus set to GENERATED (default): creates a random PIN for the new card.
pinStatus set to WAITING: the card waits for you to set the PIN later. Enfuce places no time limit on the wait — if no PIN is set, the card stays in WAITING and is never sent for embossing. If your customer wants to revert to a random PIN before setting one themselves, send a request to the Partially Update Card Endpoint with pinStatus set to GENERATED.

The same pinStatus options apply to Reissue and Replace card requests.

The card cannot be included in the embossing file while pinStatus is WAITING; it is sent for plastic production only once the PIN is set and the status changes to SET.

Set PIN process

If the pinStatus was set to WAITING, the PIN can be set through the process below. Your back-end only ever handles an opaque token — never the PIN itself, encrypted or otherwise.

Authenticate the cardholder

The cardholder completes Strong Customer Authentication (SCA) and initiates “set PIN” in your mobile or web application.

Request a PIN control access token

Your back-end requests a temporary token for the card from Enfuce, via the Request PIN Control Access Token endpoint, with scope set to SET_PIN:

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

sequenceNumber is not applicable to the SET_PIN scope. A card only ever has one version waiting for a PIN at a time, so the PIN is always set on the latest version.

Receive the token and URLs

Enfuce responds with a unique id and two URLs:

{
  "id": "a1b2c3d4-…",
  "pinUrl": "{{host}}/issuer-web/pin/set",
  "pinFrameUrl": "{{host}}/issuer-web/pin/set/frame"
}

The id is valid for 30 seconds — the deadline for the customer’s device to open the page and start the flow.

Open the hosted PIN page

With this id and one of the URLs, the app opens the hosted PIN page. Mobile app (webview) — POST to pinUrl with the id in a field named pinControlId:

curl --location "{{pinUrl}}" \
--header "Content-Type: application/json" \
--data "{
  \"pinControlId\": \"{{id}}\"
}"

Desktop browser — open an iframe to pinFrameUrl (GET), then post a message once it loads:

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

Hosted page handles the cryptography

An RSA 2048 key pair is generated on the device.
The public key is sent to Enfuce, which returns a Terminal Zone PIN Key (TZPK) encrypted under it.
The cardholder enters their PIN. The page builds an ISO Format 1 PIN block, encrypts it under the TZPK (3DES), and submits it directly to Enfuce.
Once the TZPK has been generated, the token is re-validated for a further 2 minutes (120 seconds) — the deadline for the cardholder to enter and submit their PIN.

PIN validation

The PIN must be exactly 4 digits and is rejected if it’s on the weak-PIN list (obvious sequences, repeats, or common patterns). The exact list is not disclosed and is updated over time. The page validates as the cardholder types and reports validity through the pin_valid callback below.

Confirmation

On success, Enfuce links the PIN to the card and includes it in the next embossing run. Your customer receives the plastic card with the PIN already set.

To confirm whether a card’s PIN was manually set or randomly generated, send a request to the Get Card Endpoint: pinStatus reads SET if manually set, GENERATED if random.

To display the hosted PIN page correctly in Postman, add an after-response script to the request that retrieves the HTML snapshot:

Open the request in Postman and select Scripts > After response.

Paste the following script into the script editor:

const requestUrl = pm.variables.replaceIn(
  pm.request.url.toString()
);

pm.visualizer.set(`
  <base href="{{baseHref}}" />
  {{{page}}}
`, {
  baseHref: requestUrl,
  page: pm.response.text()
});

Click Send, then click Visualization in the response pane to display the hosted PIN page.

The script sets the base URL for relative resources and passes the HTML response to the Postman Visualizer.

Callbacks

Android

window.android_handler.set_pin_success()

iOS

window.webkit.messageHandlers.ios_handler.postMessage({
    event: 'set_pin_success'
});

Desktop browser flow — the iframe window.postMessage()’s the same events back to the parent page, in the same format as iOS:

iframe.contentWindow.postMessage({ event: 'set_pin_success' }, targetOrigin);

Callback	Fired when
`set_pin_success()`	The PIN was successfully set.
`set_pin_error()`	There was an error setting the PIN.
`set_pin_validation_error()`	Submission was attempted with a PIN that fails validation.
`pin_valid(valid)`	Fires as the cardholder types; `valid` is a boolean for whether the current input is acceptable.

PCI and security considerations

The service is designed to avoid exposure of sensitive, PCI-categorised data to the web/app back-end — 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 a few points have direct 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. Enfuce recommends the following guidelines for issuer application development:
The app on the customer device and the related back-end should ensure the user is strongly authenticated (SCA) before being able to set the PIN.
The RSA keys must be generated by the device, and the back-end must not be able to decrypt the PIN encryption key nor the encrypted PIN block.
The app on the customer device shall not save the PIN the customer enters. After the PIN has successfully been set, it can be viewed through the View PIN flow.
App developers need to take necessary precautions to stop other apps or processes from accessing or interacting with the set PIN process.
App developers need to ensure that 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 a PIN. A strong PIN contains a combination of numbers and doesn’t include easily guessable patterns.

Other option: Pre-shared key

Enfuce recommends the hosted-page method above for all new integrations. The pre-shared key method remains supported for issuers who need it, but it brings your back-end into PCI scope and requires you to manage ZPK key material directly — this trade-off is usually only worthwhile if you want full control over the PIN-entry UI within your own app, rather than redirecting to an Enfuce-hosted page, and are prepared to take on the associated PCI responsibility yourself. 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.

In a multi-application card, the multiple card applications included in the main application inherit the same PIN.

Authenticate the cardholder

The cardholder is successfully authenticated in the issuer-provided mobile or web application.

Enter the PIN

The cardholder enters a PIN for their card.

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.

Build the encrypted PIN block

JavaScript creates the PIN block for the PIN:

Generates the PIN block in ISO Format 1.

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

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

Encrypts the clear PIN block using the pre-shared double-length 3DES ZPK (Zone PIN Key).
Converts the encrypted PIN block to a hexadecimal string (uppercase).

Submit to Enfuce

The issuer sends a request to the Set PIN Endpoint.

Confirmation

If the request is valid, the endpoint returns 200 — the encrypted PIN is set. Enfuce associates it with the card ID and includes the card in the next embossing file.

Communicate the result

The issuer communicates the response to the cardholder, who receives the plastic card with the PIN set.

Getting Started

Cards

Cardholders

PIN

Digital Wallets

Transaction Lifecycle

Data

Spend Controls

Exchange Rates

New Card Creation

Set PIN process

Callbacks

PCI and security considerations

Other option: Pre-shared key

​New Card Creation

​Set PIN process

​Callbacks

​PCI and security considerations

​Other option: Pre-shared key

New Card Creation

Set PIN process

Callbacks

PCI and security considerations

Other option: Pre-shared key