---
title: "Reveal PIN using standard encryption methods"
description: "Allow your cardholders see their personal identification number (PIN)."
url: "https://docs.adyen.com/issuing/manage-card-data/reveal-pin"
source_url: "https://docs.adyen.com/issuing/manage-card-data/reveal-pin.md"
canonical: "https://docs.adyen.com/issuing/manage-card-data/reveal-pin"
last_modified: "2026-05-24T12:54:31+02:00"
language: "en"
---

# Reveal PIN using standard encryption methods

Allow your cardholders see their personal identification number (PIN).

[View source](/issuing/manage-card-data/reveal-pin.md)

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](https://en.wikipedia.org/wiki/RSA_\(cryptosystem\)) public key and an [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) key to generate an encrypted session key.

Use the session key to request a [PIN block](https://www.pcisecuritystandards.org/glossary/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.

![](/user/pages/docs/07.issuing/17.manage-card-data/05.reveal-pin/pin-reveal.svg?decoding=auto\&fetchpriority=auto)

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

1. [Get a public key from Adyen](#get-a-public-key).
2. [Generate an AES key](#generate-aes-key).
3. [Generate an encrypted session key](#generate-session-key).
4. [Request the PIN block from Adyen](#request-pin-block).
5. [Decrypt the PIN block and reveal it in your user interface](#decrypt-pin-block).

## Requirements

Make sure that:

* You have [API credentials](/issuing/manage-access/api-credentials-web-service) for the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview).
* Your API credential has the **Bank Issuing PIN Reveal Webservice role**.

## Get a public key from Adyen

You need a base64-encoded [RSA](https://en.wikipedia.org/wiki/RSA_\(cryptosystem\)) public key to [generate an encrypted session key](#encrypt-aes-key). You must use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) to get the public key from Adyen.

To get a public key:

1. Make a GET [/publicKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/publicKey) request with the query parameter [purpose](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/publicKey#query-purpose) set to **pinReveal**.

   **Get a public key**

   #### curl

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

   #### Java

   ```java
   // Adyen Java API Library v33.0.0
   import com.adyen.Client;
   import com.adyen.enums.Environment;
   import com.adyen.model.balanceplatform.*;
   import java.time.OffsetDateTime;
   import java.util.*;
   import com.adyen.service.balancePlatform.*;

   Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST);
   // Send the request
   ManageCardPinApi service = new ManageCardPinApi(client);
   PublicKeyResponse response = service.publicKey("String", "String", null);
   ```

   #### PHP

   ```php
   <?php
   // Adyen PHP API Library v24.0.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Service\BalancePlatform\ManageCardPINApi;

   $client = new Client();
   $client->setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY");
   $client->setEnvironment(Environment::TEST);

   $requestOptions['queryParams'] = array('purpose' => 'string', 'format' => 'string');

   // Send the request
   $service = new ManageCardPINApi($client);
   $response = $service->publicKey($requestOptions);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v28.0.0
   using Adyen;
   using Environment = Adyen.Model.Environment;
   using Adyen.Model;
   using Adyen.Model.BalancePlatform;
   using Adyen.Service.BalancePlatform;

   var config = new Config()
   {
       XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Send the request
   var service = new ManageCardPINService(client);
   var response = service.PublicKey(purpose: "string", format: "string");
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v23.3.0
   const { Client, BalancePlatformAPI } = require('@adyen/api-library');

   const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" });

   // Send the request
   const balancePlatformAPI = new BalancePlatformAPI(client);
   const response = balancePlatformAPI.ManageCardPINApi.publicKey("string", "string");
   ```

   #### Go

   ```go
   // Adyen Go API Library v17.0.0
   import (
     "context"
     "github.com/adyen/adyen-go-api-library/v17/src/common"
     "github.com/adyen/adyen-go-api-library/v17/src/adyen"
     "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform"
   )
   client := adyen.NewClient(&common.Config{
     ApiKey:      "ADYEN_BALANCE_PLATFORM_API_KEY",
     Environment: common.TestEnv,
   })

   // Send the request
   service := client.BalancePlatform()
   req := service.ManageCardPINApi.PublicKeyInput()
   req = req.Purpose("string").Format("string")
   res, httpRes, err := service.ManageCardPINApi.PublicKey(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v13.3.0
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY"
   adyen.client.platform = "test" # The environment to use library in.

   query_parameters = {
     "purpose" : "string",
     "format" : "string"
   }

   # Send the request
   result = adyen.balancePlatform.manage_card_pin_api.public_key(query_parameters=query_parameters)
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v10.1.1
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY'
   adyen.env = :test # Set to "live" for live environment

   # Create the request object(s)
   query_params = {
     :purpose => 'string',
     :format => 'string'
   }

   # Send the request
   result = adyen.balancePlatform.manage_card_pin_api.public_key(query_params: query_params)
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v23.3.0
   import { Client, BalancePlatformAPI, Types } from "@adyen/api-library";

   const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" });

   // Send the request
   const balancePlatformAPI = new BalancePlatformAPI(client);
   const response = balancePlatformAPI.ManageCardPINApi.publicKey("string", "string");
   ```

   The response contains:

   * The public key
   * The expiry date of the public key

   **Response**

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

2. Pass the [publicKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/publicKey#responses-200-publicKey) to your front end.

## Generate an AES key

You need a 256-bit [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) encryption key to [generate an encrypted session key](#encrypt-aes-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](#request-a-pin-change) to Adyen. To generate the encrypted session key, encrypt the [AES key you generated](#generate-aes-key) in the previous step.

For the encryption, use:

* The [publicKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/publicKey#responses-200-publicKey) that you [received from Adyen](#get-public-key).
* The [RSA](https://en.wikipedia.org/wiki/RSA_\(cryptosystem\)) encryption algorithm, version [PKCS 1](https://en.wikipedia.org/wiki/PKCS_1).

## Request the PIN block from Adyen

Request from Adyen the [PIN block](https://www.pcisecuritystandards.org/glossary/pin-block) that contains the encrypted PIN data:

1. Make a POST  [/pins/reveal](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal) request and specify the following parameters:

   | Parameter                                                                                                                      | Description                                                            |
   | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
   | [paymentInstrumentId](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal#request-paymentInstrumentId) | The unique identifier of the card for which you are revealing the PIN. |
   | [encryptedKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal#request-encryptedKey)               | The [encrypted symmetric session key](#generate-session-key).          |

   **Request PIN block**

   #### curl

   ```bash
   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..."
   }'
   ```

   #### Java

   ```java
   // Adyen Java API Library v25.0.0
   import com.adyen.Client;
   import com.adyen.enums.Environment;
   import com.adyen.model.balancePlatform.*;
   import java.time.OffsetDateTime;
   import java.util.*;
   import com.adyen.service.balancePlatform.*;

   Client client = new Client("ADYEN_API_KEY", Environment.TEST);

   // Create the request object(s)
   RevealPinRequest revealPinRequest = new RevealPinRequest()
     .encryptedKey("75989E8881284D10153ABACF022EEA09F5...")
     .paymentInstrumentId("PI3227C223222B5BPCMFXD2XG");

   // Make the API call
   ManageCardPinApi service = new ManageCardPinApi(client);
   RevealPinResponse response = service.revealCardPin(revealPinRequest, null);
   ```

   #### PHP

   ```php
   // Adyen PHP API Library v17.4.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Model\BalancePlatform\RevealPinRequest;
   use Adyen\Service\BalancePlatform\ManageCardPINApi;

   $client = new Client();
   $client->setXApiKey("ADYEN_API_KEY");
   $client->setEnvironment(Environment::TEST);


   // Create the request object(s)
   $revealPinRequest = new RevealPinRequest();
   $revealPinRequest
     ->setEncryptedKey("75989E8881284D10153ABACF022EEA09F5...")
     ->setPaymentInstrumentId("PI3227C223222B5BPCMFXD2XG");

   // Make the API call
   $service = new ManageCardPINApi($client);
   $response = $service->revealCardPin($revealPinRequest);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v14.4.0
   using Adyen;
   using Environment = Adyen.Model.Environment;
   using Adyen.Model;
   using Adyen.Model.BalancePlatform;
   using Adyen.Service.BalancePlatform;

   var config = new Config()
   {
       XApiKey = "ADYEN_API_KEY",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Create the request object(s)
   RevealPinRequest revealPinRequest = new RevealPinRequest
   {
     EncryptedKey = "75989E8881284D10153ABACF022EEA09F5...",
     PaymentInstrumentId = "PI3227C223222B5BPCMFXD2XG"
   };

   // Make the API call
   var service = new ManageCardPINService(client);
   var response = service.RevealCardPin(revealPinRequest);
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v16.2.0
   // Require the parts of the module you want to use
   const { Client, BalancePlatformAPI } = require('@adyen/api-library');
   // Initialize the client object
   const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

   // Create the request object(s)
   const revealPinRequest = {
     paymentInstrumentId: "PI3227C223222B5BPCMFXD2XG",
     encryptedKey: "75989E8881284D10153ABACF022EEA09F5..."
   }

   // Make the API call
   const balancePlatformAPI = new BalancePlatformAPI(client);
   const response = balancePlatformAPI.ManageCardPINApi.revealCardPin(revealPinRequest);
   ```

   #### Go

   ```go
   // Adyen Go API Library v9.3.0
   import (
     "context"
     "github.com/adyen/adyen-go-api-library/v9/src/common"
     "github.com/adyen/adyen-go-api-library/v9/src/adyen"
     "github.com/adyen/adyen-go-api-library/v9/src/balancePlatform"
   )
   client := adyen.NewClient(&common.Config{
     ApiKey:      "ADYEN_API_KEY",
     Environment: common.TestEnv,
   })

   // Create the request object(s)
   revealPinRequest := balancePlatform.RevealPinRequest{
     EncryptedKey: "75989E8881284D10153ABACF022EEA09F5...",
     PaymentInstrumentId: "PI3227C223222B5BPCMFXD2XG",
   }

   // Make the API call
   service := client.BalancePlatform()
   req := service.ManageCardPINApi.RevealCardPinInput().RevealPinRequest(revealPinRequest)
   res, httpRes, err := service.ManageCardPINApi.RevealCardPin(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v12.2.0
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = "ADYEN_API_KEY"
   adyen.client.platform = "test" # The environment to use library in.

   # Create the request object(s)
   json_request = {
     "paymentInstrumentId": "PI3227C223222B5BPCMFXD2XG",
     "encryptedKey": "75989E8881284D10153ABACF022EEA09F5..."
   }

   # Make the API call
   result = adyen.balancePlatform.manage_card_pin_api.reveal_card_pin(request=json_request)
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v9.3.0
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   adyen.api_key = 'ADYEN_API_KEY'
   adyen.env = :test # Set to "live" for live environment

   # Create the request object(s)
   request_body = {
     :paymentInstrumentId => 'PI3227C223222B5BPCMFXD2XG',
     :encryptedKey => '75989E8881284D10153ABACF022EEA09F5...'
   }

   # Make the API call
   result = adyen.balancePlatform.manage_card_pin_api.reveal_card_pin(request_body)
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v16.2.0
   // Require the parts of the module you want to use
   import { Client, BalancePlatformAPI, Types } from "@adyen/api-library";
   // Initialize the client object
   const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

   // Create the request object(s)
   const revealPinRequest: Types.balancePlatform.RevealPinRequest = {
     encryptedKey: "75989E8881284D10153ABACF022EEA09F5...",
     paymentInstrumentId: "PI3227C223222B5BPCMFXD2XG"
   };

   // Make the API call
   const balancePlatformAPI = new BalancePlatformAPI(client);
   const response = balancePlatformAPI.ManageCardPINApi.revealCardPin(revealPinRequest);
   ```

   The response contains:

   * An [encryptedPinBlock](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal#responses-200-encryptedPinBlock): An [ISO Format 4 encrypted PIN block](https://listings.pcisecuritystandards.org/documents/Implementing_ISO_Format_4_PIN_Blocks_Information_Supplement.pdf)
   * A [token](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal#responses-200-token) that you need for decrypting the PIN block

   **Response**

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

2. Pass [encryptedPinBlock](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal#responses-200-encryptedPinBlock) and [token](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal#responses-200-token) to your client.

## Decrypt the PIN block and reveal the PIN

The PIN block is encrypted using the [ISO format 4 (ISO-4)](https://listings.pcisecuritystandards.org/documents/Implementing_ISO_Format_4_PIN_Blocks_Information_Supplement.pdf), 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](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/pins/reveal) [response](#request-pin-block).

To decrypt the PIN, follow these steps:

1. Decrypt the [`encryptedPinBlock` ](#id1623696161)using the 256-bit AES [key that you previously generated](#generate-aes-key). The decrypted data is an intermediate result.

2. Format the [`token` ](#id1623696161)that you received in the response. To do this:

   1. Generate a hexadecimal string of 32 characters that includes:

      1. "4" as the first character
      2. The [`token`](#id1623696161)
      3. The character "0" repeated 15 times.\
         Example: **4** + **5555341244441115** + **000000000000000**

   2. Convert this hexadecimal string into a 16-byte array.

3. Combine the decrypted PIN block and the formatted token data into one 16-byte array by doing an XOR.

4. Decrypt the result from the previous step using [RSA](https://en.wikipedia.org/wiki/RSA_\(cryptosystem\)) in [ECB mode](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_\(ECB\)), with the [key that you previously generated](#generate-aes-key).

5. 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 2, 3, 4, and 5.

For example, consider this hexadecimal array: 44**5454**aaaaaaaaaa4ae8c131f45d1056

In this example, the PIN is **5454**.

After decrypting the PIN, you can reveal it to the cardholder in your interface.