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.

Requirements

Make sure 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
   Get a public key

   curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)

   Expand view

   Copy link to code block

   Copy code

   Copy code

   curl https://balanceplatform-api-test.adyen.com/bcl/v2/publicKey?purpose=pinChange&format=pem \
   -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
   -H 'content-type: application/json' \
   -X GET \
   -d ''

   The response contains:

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

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMII...",
       "publicKeyExpiryDate": "2023-12-12"
   }

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.

   Initialize the service

   Expand view

   Copy link to code block

   Copy code

   Copy code

   let revealService = PinChangeService()

2. Call the encryptedPinBlock method, passing the publicKey and the new PIN as parameters.

   Generate encrypted PIN block

   Expand view

   Copy link to code block

   Copy code

   Copy code

   let encryptedPinBlock = revealService.encryptedPinBlock(withPem: publicKey, pin: pin)

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:

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

curl https://balanceplatform-api-test.adyen.com/bcl/v2/pins/change \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
    "paymentInstrumentId": "PI0000000000000000000001",
    "encryptedKey": "75989E8881284D10153ABACF022EEA09F5...",
    "encryptedPinBlock": "63E5060591EF65F48DD1D4FECD0FECD5",
    "token" : "8374188662676926"
}'

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