Change PIN using Adyen's iOS SDK

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:

1. Get a public key from Adyen.
2. Generate an encrypted PIN block.
3. Request a PIN change to Adyen.

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:

1. Make a GET /publicKey request, specifying the following query parameters:

   • purpose: pinChange
   • format: pem

   The response contains:

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

2. 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:

1. Initialize the PinChangeService method.

2. 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.