Change PIN

This capability enables your cardholders to securely update their card PIN, later during the card lifecycle (after the initial card PIN is set during its manufacturing). This provides convenience and flexibility to the cardholders who manage their PIN through the issuer-provided channels (web and/or mobile applications).

Change PIN currently only updates the online PIN — the PIN value Enfuce holds and checks. Enfuce does not trigger the EMV script needed to update the chip at the time the PIN is changed, so the card’s offline PIN stays unchanged. This means Change PIN is currently best suited for cards whose CVM (Cardholder Verification Method) list uses online PIN only — for example, virtual cards, or physical cards issued with online-PIN-only profiles.

Key benefits of the service:

A convenient, fully digital way for your customer to change their PIN whenever they want, with no call-centre step or reissue.
Lower support costs for you as an issuer.
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.

Online vs. offline PIN

Cards can verify a PIN in two ways: online, checked against the value Enfuce holds, or offline, checked locally by the card’s own EMV chip. Set PIN compared to Change PIN feature, perfors the PIN change before the card is manufactured, sets both — the PIN is included in the embossing file used to personalise the chip. Change PIN, performed after the card already exists, only updates the online PIN, for the reasons noted above.

Changing PIN does not initiate the embossing process as the plastic/physical card is already manufactured.

Use Cases

A cardholder can change their PIN in any of the following scenarios:

They receive a new card with a default PIN; they want to change the initial PIN to something of their preference.
The cardholder wants to change their PIN some time in future for personal security or change in preference.

Change PIN process

Change PIN uses the identical flow to Set PIN. Only two things differ: the token scope is CHANGE_PIN, and a sequenceNumber may optionally be supplied to target a specific card version (the latest version is used if omitted).

Authenticate the cardholder

Your customer initiates “change PIN” from a web or mobile application after completing Strong Customer Authentication (SCA).

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

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

The request can define which card version the PIN should be changed for. If no sequenceNumber is provided, the latest card version is used. The card version must already have a PIN set — requesting pinControl with CHANGE_PIN scope for a card version without a PIN returns 400.

Main card only. For multi-application cards, CHANGE_PIN can be requested only for the main card, not for a card application — use the main card’s cardId in the request path. Requesting it for a card application returns 400.

Receive the token and URLs

Enfuce responds with a unique id and two URLs:

{
  "id": "a1b2c3d4-…",
  "pinUrl": "{{host}}/issuer-web/pin/change",
  "pinFrameUrl": "{{host}}/issuer-web/pin/change/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
  );
});

Use set-pin as the operation here as well — it is not change-pin. This is easy to overlook, and using the wrong value will cause the integration to fail. To drive submission from your own surrounding page instead of the button inside the iframe, send a second message with operation set to set-pin-set (no other fields).

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 new 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 changes the PIN for the specified card version, and the result is shown to the cardholder.

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

The Change PIN hosted page provides the same callbacks as Set PIN. 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 changed.
`set_pin_error()`	There was an error changing 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 change 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 changed, 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 change 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.

The process is similar to the Set PIN pre-shared key method. However, it includes an additional check to ensure that a PIN already exists for the card.
The PIN is changed only for the specified card version with an encrypted PIN block in ISO format. If the card version is not specified, the PIN is changed for the latest version, by default.

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 eight 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 an uppercase hexadecimal string.

Submit to Enfuce

Send a request to the Change PIN endpoint.

Confirmation

If the request is valid, Enfuce changes the PIN for the specified card version and returns an HTTP response code indicating success or failure.

Result

If the operation is successful, Enfuce updates the card PIN, and the result is displayed to the cardholder.

Getting Started

Cards

Cardholders

PIN

Digital Wallets

Transaction Lifecycle

Data

Spend Controls

Exchange Rates

Online vs. offline PIN

Use Cases

Change PIN process

Callbacks

PCI and security considerations

Other option: Pre-shared key

​Online vs. offline PIN

​Use Cases

​Change PIN process

​Callbacks

​PCI and security considerations

​Other option: Pre-shared key

Online vs. offline PIN

Use Cases

Change PIN process

Callbacks

PCI and security considerations

Other option: Pre-shared key