In addition to allowing cardholders to view their card PIN, you can allow them to change their PIN within your app. 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 Adyen's Card Reveal iOS SDK. With this SDK, you can generate a PIN block that contains the new PIN that your cardholder wants to assign to their Adyen-issued card.
You must send the encrypted 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:
Before you begin
Ensure that:
-
You have API credentials for the Configuration API.
-
Your API credential has the Bank Issuing PIN Change Webservice role.
-
Your application uses iOS version 13.0 or higher.
-
You installed Adyen's Card Reveal iOS SDK.
Get a public key from Adyen
You need a base64-encoded RSA public key to generate an encrypted session key. Use the Configuration API to get the public key from Adyen.
To get a public key:
-
Make a GET /publicKey request, specifying the following query parameters:
The response contains:
- The public key
- The expiry date of the public key
-
Pass the publicKey to your client.
Generate an encrypted PIN block
You must embed the PIN in an encrypted PIN block before sending it to Adyen. Do this with Adyen's Card Reveal iOS SDK as follows:
-
Initialize the
PinChangeService
method. -
Call the
encryptedPinBlock
method, passing the publicKey and the new PIN as parameters.
Now, the encryptedPinBlock
object contains the following data:
- The encryptedPinBlock that you must send to Adyen.
- The symmetric session encryptedKey that you need to securely send the PIN block to Adyen.
- The token that Adyen needs to decrypt your PIN block.
Request a PIN change to Adyen
To request a PIN change, make a POST /pins/change call and specify the following request parameters:
Parameter | Description |
---|---|
paymentInstrumentId | The unique identifier of the card for which you are changing the PIN. |
encryptedKey | The symmetric session AES key. |
token | The token that you used to generate the encrypted PIN block. |
encryptedPinBlock | The encrypted PIN block. |
The following code sample shows how to request a PIN change.
The response contains the status of the request. Possible values: completed, pending, unavailable.