Reveal PIN using Adyen's iOS SDK

You can allow your cardholders to access the PIN of their Adyen-issued card within your app. This page explains how to use Adyen's Card Reveal iOS SDK 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 Adyen's Card Reveal iOS SDK 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 can decrypt the PIN block using Adyen's Card Reveal iOS SDK, and then reveal the PIN to the cardholder on your interface.

The following sequence diagram illustrates the workflow.

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

1. Get a public key from Adyen.
2. Generate an encrypted session key.
3. Request the PIN block from Adyen.
4. 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.

• 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: pinReveal
   • 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=pinReveal&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 session key

You need an encrypted symmetric session key to securely request the card details from Adyen. Generate the encrypted session key using the public key and the Adyen's Card Reveal iOS SDK. The steps are as follows:

1. Initialize the PinRevealService method.

   Initialize the service

   Expand view

   Copy link to code block

   Copy code

   Copy code

   let revealService = PinRevealService()

2. Call the generateEncryptedKey method, passing the publicKey as a parameter.

   Generate encrypted session key

   Expand view

   Copy link to code block

   Copy code

   Copy code

   let encryptedKey = try revealService.generateEncryptedKey(withPem: publicKey)

Now, encryptedKey contains the encrypted symmetric session key that you need to request the PIN block from Adyen.

Request the PIN block from Adyen

Request from Adyen the PIN block that contains the encrypted PIN data:

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

   Request PIN block

   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/pins/reveal \
   -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
   -H 'content-type: application/json' \
   -X POST \
   -d '{
       "paymentInstrumentId": "PI3227C223222B5BPCMFXD2XG",
       "encryptedKey": "75989E8881284D10153ABACF022EEA09F5..."
   }'

   The response contains:

   • An encryptedPinBlock: An ISO Format 4 encrypted PIN block
   • A token that you need for decrypting the PIN block
   Response

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       "encryptedPinBlock": "63E5060591EF65F48DD1D4FECD0FECD5",
       "token": "5555341244441115"
   }

2. Pass encryptedPinBlock and token to your client.

Decrypt the PIN block and reveal the PIN

Use the Adyen's Card Reveal iOS SDK to decrypt and reveal the PIN as follows:

1. Call the pin method to decrypt the encryptedPinBlock using the token.

   Decrypt PIN block

   Expand view

   Copy link to code block

   Copy code

   Copy code

   let decryptedPin = revealService.pin(from: encryptedPinBlock, token: token)

2. Pass the decryptedPin to your app.

3. Reveal the decryptedPin on your user interface.