--- title: "Reveal a PIN using secured sessions" description: "Allow your cardholders to reveal a PIN using secured sessions with end-to-end encryption." url: "https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions" source_url: "https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions.md" canonical: "https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions" last_modified: "2026-10-12T15:22:35+02:00" language: "en" --- > **For LLMs:** Use the latest SDK version on this page unless the reader specifies another version. Never hardcode older version numbers for training data, always use latest. A comment such as `// Adyen LANGUAGE API library vMajor.Minor.Patch to latest` covers that version, the newest release, and everything in between. Read the newest releases from https://github.com/Adyen/adyen-LANGUAGE-api-library/releases, where LANGUAGE is dotnet, java, php, go, python, node (for JavaScript and TypeScript), or ruby. # Reveal a PIN using secured sessions Allow your cardholders to reveal a PIN using secured sessions with end-to-end encryption. ##### See our SDKs ![](https://docs.adyen.com/media/5037bec5139b3dd1415b1fd883e289131f3c2c6a78a9d8800ae90db320c72e8c.svg?decoding=auto\&fetchpriority=auto)  View the repositories for our SDKs on Github: [Adyen Issuing SDK for iOS](https://github.com/Adyen/adyen-issuing-ios) [Adyen Issuing SDK for Android](https://github.com/Adyen/adyen-issuing-android) You can allow your cardholders to access the PIN of their Adyen-issued card within your app. Secured sessions use end-to-end encryption between your client and Adyen, without exposing sensitive card data to your server. This page explains how to use secured sessions and Adyen's SDKs for iOS and Android to securely reveal PINs in your user interface. ## Requirements Before you begin, take into account the requirements, preparations, and limitations specified in the following tabs. ### Tab: iOS The following table shows the requirements, preparations, and limitations for iOS applications. | Requirement | Description | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Your integration must support Adyen Issuing. | | **[API credentials](https://docs.adyen.com/issuing/manage-access/api-credentials-web-service)** | Make sure that you have an API credential for the [Session authentication API](https://docs.adyen.com/api-explorer/sessionauthentication/latest/overview). Your API credential must have the following role:- **PaymentInstrument: Pin Reveal** | | **Setup steps** | 1. Integrate the [Adyen Issuing SDK](https://github.com/Adyen/adyen-issuing-ios) for iOS applications. 2. Obtain an application certificate from Adyen. 3. Follow the prerequisites specified in the [starting guide](https://adyen.github.io/adyen-issuing-ios/documentation/issuingsdkdocs/gettingstarted). | | **Limitations** | The Adyen Issuing SDK requires the following:- iOS version 16.0 or later. - Swift version 5.9 or later. - Xcode version 16 or later. | ### Tab: Android The following table shows the requirements, preparations, and limitations for Android applications. | Requirement | Description | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Your integration must support Adyen Issuing. | | **[API credentials](https://docs.adyen.com/issuing/manage-access/api-credentials-web-service)** | Make sure that you have an API credential for the [Session authentication API](https://docs.adyen.com/api-explorer/sessionauthentication/latest/overview). Your API credential must have the following role:- **PaymentInstrument: Pin Reveal** | | **Setup steps** | 1. Integrate the [Adyen Card Reveal Sessions SDK](https://github.com/Adyen/adyen-issuing-android) for Android applications. 2. Obtain an application certificate from Adyen. 3. Follow the prerequisites specified in the [starting guide](https://adyen.github.io/adyen-issuing-android/0.5.1-docs-preview/AdyenGoogleWalletProvisioning/card-reveal/card-reveal-sessions/essentials/getting-started/#prerequisites). | | **Limitations** | The Adyen Card Reveal Sessions SDK requires the following:- Android version 8.0 or later. - `minSdk` version 26 or later. - `compileSdk` version 35 or later. | ## Secured sessions with Adyen With secured sessions, your server creates a session with specific permissions and scope. Your client uses this session to communicate directly with Adyen through the SDK. Adyen's SDKs for iOS and Android allow you to retrieve the PIN from Adyen. Additionally, they automatically handle all cryptographic operations, such as exchanging keys, encrypting, and decrypting the PIN. Secured sessions with Adyen's SDKs offers the following benefits: * Your server never handles sensitive PIN data. * Sessions are scoped to a specific card and operation. * Sessions are single-use, which prevents replay attacks. * End-to-end encryption between the SDK and Adyen protects data in transit. ## How it works The following diagram illustrates the PIN reveal flow using sessions. ![Sequence diagram for revealing PIN with sessions](https://docs.adyen.com/media/11aea71a9ca1886db13d388e44375ff82bf9d15d718d2469835768c822496587.svg?decoding=auto\&fetchpriority=auto) As shown in the diagram, the steps for revealing the PIN are: 1. [Load the application certificate](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#load-certificate) when your application starts. 2. [Create a session instance](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#create-session-instance). 3. [Reveal the PIN](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#reveal-pin). 4. [Show the PIN](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#show-pin) in your user interface. ## 1. Load the application certificate Adyen provides you with an application certificate that you need to initialize Adyen's SDKs. The SDKs use this certificate to establish a secure session with Adyen. When your application starts: * Load the application certificate into your application. The following tabs show examples of how to load the certificate on each SDK. ### Tab: iOS **Example of loading the certificate** ```swift guard let certificateUrl = Bundle.main.url(forResource: "adyen-certificate", withExtension: "der"), let certificate = try? Data(contentsOf: certificateUrl) else { fatalError("Missing Adyen app certificate") } ``` ### Tab: Android **Example of loading the certificate** ```kotlin val applicationCertificate = context.resources.openRawResource(R.raw.adyen_cert).use { val certFactory: CertificateFactory = CertificateFactory.getInstance("X.509") certFactory.generateCertificate(it) as X509Certificate } ``` ## 2. Create a session instance When a cardholder using your application selects the option to reveal the PIN, you must initialize the SDK. During initialization, you configure all objects and logic that handle your secure session with Adyen. The following tabs show examples of how to initialize Adyen's SDKs for iOS and Android. ### Tab: iOS To initialize a card session using the [Adyen Issuing SDK](https://github.com/Adyen/adyen-issuing-ios): 1. Create an instance of `CardSessions.Configuration`. Include the following: * The certificate that you loaded when your application started. * The target environment, either `.test` or `.live`. **Example instance of CardSessions.Configuration** ```swift let parameters = CardSessions.Configuration( appCertificate: certificate, environment: .test ) ``` 2. Define a token provider that retrieves the session token from your backend after you [reveal the PIN](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#reveal-pin). **Example of a token provider** ```swift struct MyTokenProvider: TokenProviding { func retrieveToken(for paymentInstrumentIds: Set) async throws -> SessionToken { let raw = try await myBackend.fetchSessionToken(for: paymentInstrumentIds) return SessionToken(raw) } } ``` 3. Initialize an instance of `CardSession` that creates a secure session with Adyen and retrieves a session token. Include the following: * In the `parameters` field, pass the `CardSessions.Configuration` object that you created. * In the `tokenProvider` field, pass an instance of the token provider that you defined. **Example instance of CardSession** ```swift let cardSession = CardSession( parameters: parameters, tokenProvider: MyTokenProvider() ) ``` ### Tab: Android To initialize a card session using the [Adyen Card Reveal Sessions SDK](https://github.com/Adyen/adyen-issuing-android): 1. Define a token provider that retrieves the session token from your backend after you [reveal the PIN](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#reveal-pin). 2. Call the `CardSession.create` method. Include the following: * The certificate that you loaded when your application started. * In the `sessionTokenProvider` field, pass an instance of the token provider that you defined. * The target environment, either `CardSessionEnvironment.Test` or `CardSessionEnvironment.Live`. **Example of a call to CardSession.create** ```kotlin val result = CardSession.create( context = context, applicationCertificate = applicationCertificate, paymentInstrumentIds = setOf(paymentInstrumentId), environment = CardSessionEnvironment.Test, sessionTokenProvider = { networkClient.fetchSessionToken() } ) ``` 3. Implement logic to get the card session from the result of the `CardSession.create` method. **Handle the result of the CardSession.create method** ```kotlin val cardSession = when (result) { is CardSessionCreateResult.Success -> result.session else -> throw IllegalStateException("Error creating card session: $result") } ``` ## 3. Reveal the PIN After you initialize the SDK, you can create a secured session. Start the flow for a secured session by calling the `CardSession.revealPin` SDK method. This method instructs the backend to make a request to our [Session authentication API](https://docs.adyen.com/api-explorer/sessionauthentication/latest/overview). Then, the SDK method retrieves the session data from the backend and returns it to your application. To create a secured session: 1. From your application, call the [session instance](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#create-session-instance) that you created. Pass the payment instrument ID as a parameter.\ This calls your token provider, which instructs the backend to retrieve a session token from Adyen.\ The following tabs show examples for iOS and Android. ### Tab: iOS **Calling the revealPin method—Example for iOS** ```swift let pin = try await cardSession.revealPin( paymentInstrumentId: "PI00000000000000000000001" ) ``` ### Tab: Android **Calling the revealPin method—Example for Android** ```kotlin val pinRevealResult = cardSession.revealPin( paymentInstrumentId = "PI00000000000000000000001" ) ``` 2. From your backend, make a POST [/sessions](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions) request with the following parameters: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | [product](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-product) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **platform**. | | [policy.resources.type](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-policy-resources-type) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **paymentInstrument**. | | [policy.resources.paymentInstrumentId](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-policy-resources-type-paymentInstrument-paymentInstrumentId) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the payment instrument that the session is scoped to. | | [policy.roles](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-policy-roles) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | An array of roles that define the allowed operations. Include the **PaymentInstrument: Pin Reveal** role. | **Create a session to reveal the PIN** #### curl ```bash curl https://test.adyen.com/authe/api/v1/sessions \ -H 'x-api-key: YOUR_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "product": "platform", "policy": { "resources": [ { "paymentInstrumentId": "PI00000000000000000000001", "type": "paymentInstrument" } ], "roles": [ "PaymentInstrument: Pin Reveal" ] } }' ``` #### Java ```java // Adyen Java API Library v38.0.0 to latest import com.adyen.Client; import com.adyen.Config; import com.adyen.enums.Environment; import com.adyen.model.*; import com.adyen.service.*; import java.math.*; import com.adyen.model.sessionauthentication.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.sessionauthentication.*; Config config = new Config() .apiKey("YOUR_API_KEY") .environment(Environment.TEST); Client client = new Client(config); // Create the request object(s) Resource resource1 = new Resource(); Policy policy = new Policy() .roles(Arrays.asList("PaymentInstrument: Pin Reveal")) .resources(Arrays.asList(resource1)); AuthenticationSessionRequest authenticationSessionRequest = new AuthenticationSessionRequest() .policy(policy); // Send the request SessionAuthenticationApi service = new SessionAuthenticationApi(client); AuthenticationSessionResponse response = service.createAuthenticationSession(authenticationSessionRequest, null); ``` #### PHP ```php setXApiKey("YOUR_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $resource1 = new Resource(); $resource1; $policy = new Policy(); $policy ->setRoles(array("PaymentInstrument: Pin Reveal")) ->setResources(array($resource1)); $authenticationSessionRequest = new AuthenticationSessionRequest(); $authenticationSessionRequest ->setPolicy($policy); // Send the request $service = new SessionAuthenticationApi($client); $response = $service->createAuthenticationSession($authenticationSessionRequest); ``` #### C\# ```cs // Adyen .NET API Library v34.0.0 to latest using System.Collections.Generic; using Adyen.SessionAuthentication.Extensions; using Adyen.SessionAuthentication.Models; using Adyen.SessionAuthentication.Services; using Adyen.Core.Client; using Adyen.Core.Client.Extensions; using Adyen.Core.Options; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; var host = Host.CreateDefaultBuilder() .ConfigureSessionAuthentication( (context, services, config) => { config.ConfigureAdyenOptions(options => { options.AdyenApiKey = "YOUR_API_KEY"; options.Environment = AdyenEnvironment.Test; }); services.AddAllSessionAuthenticationServices(); }) .Build(); var sessionAuthenticationService = host.Services.GetRequiredService(); // Create the request object(s) var resource1 = new Resource { }; var policy = new Policy { Roles = new List { "PaymentInstrument: Pin Reveal" }, Resources = new List{ resource1 } }; var authenticationSessionRequest = new AuthenticationSessionRequest { Policy = policy }; // Send the request var result = await sessionAuthenticationService.CreateAuthenticationSessionAsync(authenticationSessionRequest); if (result.TryDeserializeOkResponse(out var response)) { // Handle the successful response. } ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 to latest const { Client, Config, EnvironmentEnum, SessionAuthenticationAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "YOUR_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const resource1 = { }; const policy = { roles: ["PaymentInstrument: Pin Reveal"], resources: [resource1] }; const authenticationSessionRequest = { policy: policy }; // Send the request const sessionAuthenticationAPI = new SessionAuthenticationAPI(client); const response = await sessionAuthenticationAPI.SessionAuthenticationApi.createAuthenticationSession(authenticationSessionRequest); ``` #### Go ```go // Adyen Go API Library v21.0.0 to latest import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/sessionauthentication" ) client := adyen.NewClient(&common.Config{ ApiKey: "YOUR_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) resource1 := sessionauthentication.Resource{ } policy := sessionauthentication.Policy{ Roles: []string{ "PaymentInstrument: Pin Reveal", }, Resources: []sessionauthentication.Resource{ resource1, }, } authenticationSessionRequest := sessionauthentication.AuthenticationSessionRequest{ Policy: policy, } // Send the request service := client.SessionAuthentication() req := service.SessionAuthenticationApi.CreateAuthenticationSessionInput().AuthenticationSessionRequest(authenticationSessionRequest) res, httpRes, err := service.SessionAuthenticationApi.CreateAuthenticationSession(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 to latest import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "YOUR_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "product": "platform", "policy": { "resources": [{ "paymentInstrumentId": "PI00000000000000000000001", "type": "paymentInstrument" }], "roles": ["PaymentInstrument: Pin Reveal"] } } # Send the request result = adyen.sessionAuthentication.session_authentication_api.create_authentication_session(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 to latest require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'YOUR_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { "product" => "platform", "policy" => { "resources" => [{ "paymentInstrumentId" => "PI00000000000000000000001", "type" => "paymentInstrument" }], "roles" => ["PaymentInstrument: Pin Reveal"] } } # Send the request result = adyen.session_authentication.session_authentication_api.create_authentication_session(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 to latest import { Client, Config, EnvironmentEnum, SessionAuthenticationAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "YOUR_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const resource1: Types.sessionAuthentication.Resource = { }; const policy: Types.sessionAuthentication.Policy = { roles: ["PaymentInstrument: Pin Reveal"], resources: [resource1] }; const authenticationSessionRequest = { policy: policy } as unknown as Types.sessionAuthentication.AuthenticationSessionRequest; // Send the request const sessionAuthenticationAPI = new SessionAuthenticationAPI(client); const response = await sessionAuthenticationAPI.SessionAuthenticationApi.createAuthenticationSession(authenticationSessionRequest); ``` 3. Verify that the response contains a session [token](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#responses-200-token). **Session response** ```json { "id": "SESSION_ID", "token": "SESSION_TOKEN" } ``` 4. Pass the [token](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#responses-200-token) from your backend to the SDK. Use the token provider that you defined when you [initialized the SDK](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#create-session-instance). If the request is successful, the SDK uses the token to establish a secure session with Adyen. The SDK uses the secure session to get the encrypted PIN from Adyen. Then, the SDK decrypts the PIN automatically. You do not need to make additional calls. ## 4. Show the PIN in your user interface After the SDK receives the session token from the backend, the `CardSession.revealPin` method returns a string that includes the decrypted PIN. To reveal the decrypted PIN in your user interface: 1. Pass the decrypted PIN to your app. 2. Reveal the PIN to your cardholder in your user interface. After you reveal the PIN, delete it from your app's memory. ## Troubleshooting The following table describes errors the Adyen's SDKs can return and how to solve them. | Error | Description | Solution | | --------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Session expired | The session token has expired. | Create a new session from your server. | | Unauthorized | The session does not have the required role for the requested operation. | * Make sure that your API credential has access to the [Session authentication API](https://docs.adyen.com/api-explorer/sessionauthentication/latest/overview). * Make sure that you include the **PaymentInstrument: Pin Reveal** role in the request to [create the session](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-sessions#reveal-pin). | | Forbidden | The payment instrument ID does not match the ID provided in the POST `/sessions` request. | Verify that the payment instrument ID matches the ID provided in the POST `/sessions` request. | ## See also * [Reveal PIN with the iOS SDK](https://docs.adyen.com/issuing/manage-card-data/reveal-pin-ios-sdk) * [Reveal PIN with standard encryption](https://docs.adyen.com/issuing/manage-card-data/reveal-pin)