You can allow your cardholders to access the PIN of their Adyen-issued card within your app or website. This page explains how to implement a feature to securely reveal PINs in your user interface.
To reveal a PIN in your user interface, you must first get the PIN data from Adyen. To securely request the data, you use a base64-encoded RSA public key and an Advanced Encryption Standard (AES) key to generate an encrypted session key.
Use the session key to request a PIN block from Adyen. This PIN block contains the encrypted PIN data assigned to the Adyen-issued card. You must extract the PIN from the decrypted PIN block and then reveal the PIN to the cardholder in your interface.
The following sequence diagram illustrates the workflow.
As shown in the diagram, the steps for revealing a PIN are:
- Get a public key from Adyen.
- Generate an AES key.
- Generate an encrypted session key.
- Request the PIN block from Adyen.
- Decrypt the PIN block and reveal it in your user interface.
Requirements
Make sure that:
- You have API credentials for the Configuration API.
- Your API credential has the Bank Issuing PIN Reveal 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:
-
Make a GET /publicKey request with the query parameter purpose set to pinReveal.
The response contains:
- The public key
- The expiry date of the public key
-
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.
Request the PIN block from Adyen
Request from Adyen the PIN block that contains the encrypted PIN data:
-
Make a POST /pins/reveal request and specify the following parameters:
Parameter Description paymentInstrumentId The unique identifier of the card for which you are revealing the PIN. encryptedKey The encrypted symmetric session key. The response contains:
- An encryptedPinBlock: An ISO Format 4 encrypted PIN block
- A token that you need for decrypting the PIN block
-
Pass encryptedPinBlock and token to your client.
Decrypt the PIN block and reveal the PIN
The PIN block is encrypted using the ISO format 4 (ISO-4), a standard encryption method. Because the PIN itself is only 4 characters, a token is used as an intermediate step for decryption. Both the token and the PIN block are included in the POST /pins/reveal response.
To decrypt the PIN, follow these steps:
- Decrypt the
encryptedPinBlockusing the 256-bit AES key that you previously generated. The decrypted data is an intermediate result. -
Format the
tokenthat you received in the response. To do this:-
Generate a hexadecimal string of 32 characters that includes:
- "4" as the first character
- The
token - The character "0" repeated 15 times.
Example: 4 + 5555341244441115 + 000000000000000
-
Convert this hexadecimal string into a 16-byte array.
-
- Combine the decrypted PIN block and the formatted token data into one 16-byte array by doing an XOR.
- Decrypt the result from the previous step using RSA in ECB mode, with the key that you previously generated.
- Convert the resulting bytes into a hexadecimal string.
The decrypted PIN is within the obtained hexadecimal string. Assuming that the initial character of the string is in position 0, you will find the digits of the PIN in positions 1, 2, 3, and 4.
For example, consider this hexadecimal array: 35454f1d7b2d252964ac1322e5d2e80b
In this example, the PIN is 5454.
After decrypting the PIN, you can reveal it to the cardholder in your interface.