Change PIN using standard encryption methods

In addition to allowing cardholders to view their card PIN, you can allow them to change their PIN within your app or website. This page explains how to implement a feature to securely change PINs in your user interface.

To securely request a PIN change, you must use a base64-encoded RSA public key and an Advanced Encryption Standard (AES) key to generate an encrypted session key.

Use the session key and a 16-digit token to generate an encrypted PIN block. This PIN block contains the new PIN that your cardholder wants to assign to their Adyen-issued card. You must send the PIN block to Adyen in a POST  /pins/change request. Adyen then decrypts the PIN block and registers the new PIN.

The following sequence diagram illustrates the workflow.

As shown in the diagram, the steps for changing a PIN are:

1. Get a public key from Adyen.
2. Generate an AES key.
3. Generate an encrypted session key.
4. Generate an encryption token.
5. Generate an encrypted PIN block.
6. Request a PIN change to Adyen.

Requirements

Make sure that:

• You have API credentials for the Configuration API.
• Your API credential has the Bank Issuing PIN Change Webservice role.

Get a public key from Adyen

You need a base64-encoded RSA public key to generate an encrypted session key. You must use the Configuration API to get the public key from Adyen.

To get a public key:

1. Make a GET /publicKey request with the query parameter purpose set to pinChange.

   The response contains:

   • The public key
   • The expiry date of the public key

2. Pass the publicKey to your front end.

Generate an AES key

You need a 256-bit AES encryption key to generate an encrypted session key. You can generate this key by using a random bit generator.

Generate an encrypted session key

You need an encrypted symmetric session key to securely request the PIN change to Adyen. To generate the encrypted session key, encrypt the AES key you generated in the previous step.

For the encryption, use:

• The publicKey that you received from Adyen.
• The RSA encryption algorithm, version PKCS 1.

Generate an encryption token

You need a token as an intermediate step to generate the encrypted PIN block. To get a token, generate a 16-digit random number that does not contain zeros.

Example token: 8374188662676926

Generate an encrypted PIN block

You must embed the PIN in an encrypted PIN block before sending it to Adyen. Encrypt the PIN block using the ISO format 4 (ISO-4) encryption method.

To encrypt a PIN block using the ISO format 4 method:

1. Format the token that you previously generated. To do this, create a hexadecimal string of 32 characters as follows:
   1. "4" as the first character
   2. The token
   3. The character "0" repeated 15 times.
      Example: 4 + 8374188662676926 + 000000000000000
2. Convert the formatted token into a 16-byte array.
3. Format the new PIN. To do this, create a hexadecimal string of 32 characters as follows:
   1. The string "44"
   2. The new PIN
   3. 10 times the character "A"
   4. 16 random hexadecimal characters
      Example: 44 + 5454 + AAAAAAAAAA + 70cd3917e96891f8
4. Convert the formatted PIN into a 16-byte array.
5. Encrypt the 16-byte PIN data using AES in ECB mode with the key that you previously generated.
6. Combine the 16-byte token data and the encrypted PIN data into one 16-byte array by doing an XOR.
7. Encrypt the combined array using AES in ECB mode with the key that you previously generated.
8. Convert this encrypted data into a hexadecimal string.

The hexadecimal string is the encrypted PIN block that you must send to Adyen when you request the PIN change.

Request a PIN change to Adyen

To request a PIN change, make a POST  /pins/change call and specify the following request parameters:

The following code sample shows how to request a PIN change.

The response contains the status of the request. Possible values: completed, pending, unavailable.