{"title":"Reveal a PIN using secured sessions","category":"default","creationDate":1791811355,"content":"<div class=\"additional-info-block output-inline\">\n<h5 class=\"article__heading additional-info-block__title\">See our SDKs<\/h5><div class=\"additional-info-block__body\"><p><img style=\"width: 25px;\" alt=\"\" src=\"\/media\/5037bec5139b3dd1415b1fd883e289131f3c2c6a78a9d8800ae90db320c72e8c.svg?decoding=auto&amp;fetchpriority=auto\" \/>&nbsp;&nbsp;View the repositories for our SDKs on Github:<\/p><p><a href=\"https:\/\/github.com\/Adyen\/adyen-issuing-ios\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Adyen Issuing SDK for iOS<\/a><\/p><p><a href=\"https:\/\/github.com\/Adyen\/adyen-issuing-android\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Adyen Issuing SDK for Android<\/a><\/p><\/div><\/div>\n\n<p>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.<\/p>\n<p>This page explains how to use secured sessions and Adyen's SDKs for iOS and Android to securely reveal PINs in your user interface.<\/p>\n<h2>Requirements<\/h2>\n<p>Before you begin, take into account the requirements, preparations, and limitations specified in the following tabs.<\/p>\n\n<div id=\"tabwqhHX\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;iOS&quot;,&quot;content&quot;:&quot;\\n&lt;p&gt;The following table shows the requirements, preparations, and limitations for iOS applications.&lt;\/p&gt;\\n&lt;table&gt;\\n&lt;thead&gt;\\n&lt;tr&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Requirement&lt;\/th&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Description&lt;\/th&gt;\\n&lt;\/tr&gt;\\n&lt;\/thead&gt;\\n&lt;tbody&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;Integration type&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;Your integration must support Adyen Issuing.&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;&lt;a href=\\&quot;\/issuing\/manage-access\/api-credentials-web-service\\&quot;&gt;API credentials&lt;\/a&gt;&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;Make sure that you have an API credential for the  &lt;a href=\\&quot;https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/overview\\&quot; class=\\&quot; external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;Session authentication API&lt;\/a&gt;. Your API credential must have the following role:&lt;ul&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;&lt;strong&gt;PaymentInstrument: Pin Reveal&lt;\/strong&gt;&lt;\/li&gt;&lt;\/ul&gt;&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;Setup steps&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;ol&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Integrate the &lt;a href=\\&quot;https:\/\/github.com\/Adyen\/adyen-issuing-ios\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Adyen Issuing SDK&lt;\/a&gt; for iOS applications.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Obtain an application certificate from Adyen.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Follow the prerequisites specified in the &lt;a href=\\&quot;https:\/\/adyen.github.io\/adyen-issuing-ios\/documentation\/issuingsdkdocs\/gettingstarted\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;starting guide&lt;\/a&gt;.&lt;\/li&gt;&lt;\/ol&gt;&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;Limitations&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;The Adyen Issuing SDK requires the following:&lt;ul&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;iOS version 16.0 or later.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Swift version 5.9 or later.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Xcode version 16 or later.&lt;\/li&gt;&lt;\/ul&gt;&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;\/tbody&gt;\\n&lt;\/table&gt;\\n&quot;,&quot;altTitle&quot;:&quot;ios&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;ios&quot;},{&quot;title&quot;:&quot;Android&quot;,&quot;content&quot;:&quot;\\n&lt;p&gt;The following table shows the requirements, preparations, and limitations for Android applications.&lt;\/p&gt;\\n&lt;table&gt;\\n&lt;thead&gt;\\n&lt;tr&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Requirement&lt;\/th&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Description&lt;\/th&gt;\\n&lt;\/tr&gt;\\n&lt;\/thead&gt;\\n&lt;tbody&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;Integration type&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;Your integration must support Adyen Issuing.&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;&lt;a href=\\&quot;\/issuing\/manage-access\/api-credentials-web-service\\&quot;&gt;API credentials&lt;\/a&gt;&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;Make sure that you have an API credential for the  &lt;a href=\\&quot;https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/overview\\&quot; class=\\&quot; external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;Session authentication API&lt;\/a&gt;. Your API credential must have the following role:&lt;ul&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;&lt;strong&gt;PaymentInstrument: Pin Reveal&lt;\/strong&gt;&lt;\/li&gt;&lt;\/ul&gt;&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;Setup steps&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;ol&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Integrate the &lt;a href=\\&quot;https:\/\/github.com\/Adyen\/adyen-issuing-android\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Adyen Card Reveal Sessions SDK&lt;\/a&gt; for Android applications.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Obtain an application certificate from Adyen.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Follow the prerequisites specified in the &lt;a href=\\&quot;https:\/\/adyen.github.io\/adyen-issuing-android\/0.5.1-docs-preview\/AdyenGoogleWalletProvisioning\/card-reveal\/card-reveal-sessions\/essentials\/getting-started\/#prerequisites\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;starting guide&lt;\/a&gt;.&lt;\/li&gt;&lt;\/ol&gt;&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;strong&gt;Limitations&lt;\/strong&gt;&lt;\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;The Adyen Card Reveal Sessions SDK requires the following:&lt;ul&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;Android version 8.0 or later.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;&lt;code&gt;minSdk&lt;\/code&gt; version 26 or later.&lt;\/li&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;&lt;code&gt;compileSdk&lt;\/code&gt; version 35 or later.&lt;\/li&gt;&lt;\/ul&gt;&lt;\/td&gt;\\n&lt;\/tr&gt;\\n&lt;\/tbody&gt;\\n&lt;\/table&gt;\\n&quot;,&quot;altTitle&quot;:&quot;android&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;android&quot;}]\"\n            :should-update-when-url-changes='true'>\n        <\/tabs>\n    <\/div>\n<\/div>\n\n<h2>Secured sessions with Adyen<\/h2>\n<p>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.<\/p>\n<p>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.<\/p>\n<p>Secured sessions with Adyen's SDKs offers the following benefits:<\/p>\n<ul>\n<li>Your server never handles sensitive PIN data.<\/li>\n<li>Sessions are scoped to a specific card and operation.<\/li>\n<li>Sessions are single-use, which prevents replay attacks.<\/li>\n<li>End-to-end encryption between the SDK and Adyen protects data in transit.<\/li>\n<\/ul>\n<h2>How it works<\/h2>\n<p>The following diagram illustrates the PIN reveal flow using sessions.<\/p>\n<p><img alt=\"Sequence diagram for revealing PIN with sessions\" src=\"\/media\/11aea71a9ca1886db13d388e44375ff82bf9d15d718d2469835768c822496587.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/p>\n<p>As shown in the diagram, the steps for revealing the PIN are:<\/p>\n<ol>\n<li><a href=\"#load-certificate\">Load the application certificate<\/a> when your application starts.<\/li>\n<li><a href=\"#create-session-instance\">Create a session instance<\/a>.<\/li>\n<li><a href=\"#reveal-pin\">Reveal the PIN<\/a>.<\/li>\n<li><a href=\"#show-pin\">Show the PIN<\/a> in your user interface.<\/li>\n<\/ol>\n<h2 id=\"load-certificate\">1. Load the application certificate<\/h2>\n<p>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.<\/p>\n<p>When your application starts:<\/p>\n<ul>\n<li>\n<p>Load the application certificate into your application.<\/p>\n<p>The following tabs show examples of how to load the certificate on each SDK.<\/p>\n\n<div id=\"tab2J1HG\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;iOS&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Example of loading the certificate&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;swift\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;guard let certificateUrl = Bundle.main.url(forResource: \\\\\\&quot;adyen-certificate\\\\\\&quot;, withExtension: \\\\\\&quot;der\\\\\\&quot;),\\\\n      let certificate = try? Data(contentsOf: certificateUrl) else {\\\\n    fatalError(\\\\\\&quot;Missing Adyen app certificate\\\\\\&quot;)\\\\n}\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&quot;,&quot;altTitle&quot;:&quot;ios&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;ios&quot;},{&quot;title&quot;:&quot;Android&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Example of loading the certificate&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;kotlin\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;val applicationCertificate = context.resources.openRawResource(R.raw.adyen_cert).use {\\\\n    val certFactory: CertificateFactory = CertificateFactory.getInstance(\\\\\\&quot;X.509\\\\\\&quot;)\\\\n    certFactory.generateCertificate(it) as X509Certificate\\\\n}\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&quot;,&quot;altTitle&quot;:&quot;android&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;android&quot;}]\"\n            :should-update-when-url-changes='true'>\n        <\/tabs>\n    <\/div>\n<\/div>\n\n<\/li>\n<\/ul>\n<h2 id=\"create-session-instance\">2. Create a session instance<\/h2>\n<p>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.<\/p>\n<p>The following tabs show examples of how to initialize Adyen's SDKs for iOS and Android.<\/p>\n\n<div id=\"tabgas6N\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;iOS&quot;,&quot;content&quot;:&quot;\\n&lt;p&gt;To initialize a card session using the &lt;a href=\\&quot;https:\/\/github.com\/Adyen\/adyen-issuing-ios\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Adyen Issuing SDK&lt;\/a&gt;:&lt;\/p&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;Create an instance of &lt;code&gt;CardSessions.Configuration&lt;\/code&gt;. Include the following:&lt;\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;The certificate that you loaded when your application started.&lt;\/li&gt;\\n&lt;li&gt;The target environment, either &lt;code&gt;.test&lt;\/code&gt; or &lt;code&gt;.live&lt;\/code&gt;.&lt;\/li&gt;\\n&lt;\/ul&gt;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Example instance of CardSessions.Configuration&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;swift\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;let parameters = CardSessions.Configuration(\\\\n    appCertificate: certificate,\\\\n    environment: .test \\\\n)\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&lt;\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Define a token provider that retrieves the session token from your backend after you &lt;a href=\\&quot;#reveal-pin\\&quot;&gt;reveal the PIN&lt;\/a&gt;.&lt;\/p&gt;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Example of a token provider&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;swift\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;struct MyTokenProvider: TokenProviding {\\\\n    func retrieveToken(for paymentInstrumentIds: Set&amp;lt;String&amp;gt;) async throws -&amp;gt; SessionToken {\\\\n        let raw = try await myBackend.fetchSessionToken(for: paymentInstrumentIds)\\\\n        return SessionToken(raw)\\\\n    }\\\\n}\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&lt;\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Initialize an instance of &lt;code&gt;CardSession&lt;\/code&gt; that creates a secure session with Adyen and retrieves a session token. Include the following:&lt;\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;In the &lt;code&gt;parameters&lt;\/code&gt; field, pass the &lt;code&gt;CardSessions.Configuration&lt;\/code&gt; object that you created.&lt;\/li&gt;\\n&lt;li&gt;In the &lt;code&gt;tokenProvider&lt;\/code&gt; field, pass an instance of the token provider that you defined.&lt;\/li&gt;\\n&lt;\/ul&gt;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Example instance of CardSession&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;swift\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;let cardSession = CardSession(\\\\n    parameters: parameters,\\\\n    tokenProvider: MyTokenProvider()\\\\n)\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&lt;\/li&gt;\\n&lt;\/ol&gt;\\n&quot;,&quot;altTitle&quot;:&quot;ios&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;ios&quot;},{&quot;title&quot;:&quot;Android&quot;,&quot;content&quot;:&quot;\\n&lt;p&gt;To initialize a card session using the &lt;a href=\\&quot;https:\/\/github.com\/Adyen\/adyen-issuing-android\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Adyen Card Reveal Sessions SDK&lt;\/a&gt;:&lt;\/p&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;Define a token provider that retrieves the session token from your backend after you &lt;a href=\\&quot;#reveal-pin\\&quot;&gt;reveal the PIN&lt;\/a&gt;.&lt;\/p&gt;\\n&lt;\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Call the &lt;code&gt;CardSession.create&lt;\/code&gt; method. Include the following:&lt;\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;The certificate that you loaded when your application started.&lt;\/li&gt;\\n&lt;li&gt;In the &lt;code&gt;sessionTokenProvider&lt;\/code&gt; field, pass an instance of the token provider that you defined.&lt;\/li&gt;\\n&lt;li&gt;The target environment, either &lt;code&gt;CardSessionEnvironment.Test&lt;\/code&gt; or &lt;code&gt;CardSessionEnvironment.Live&lt;\/code&gt;.&lt;\/li&gt;\\n&lt;\/ul&gt;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Example of a call to CardSession.create&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;kotlin\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;val result = CardSession.create(\\\\n    context = context,\\\\n    applicationCertificate = applicationCertificate,\\\\n    paymentInstrumentIds = setOf(paymentInstrumentId),\\\\n    environment = CardSessionEnvironment.Test,\\\\n    sessionTokenProvider = {\\\\n        networkClient.fetchSessionToken()\\\\n    }\\\\n)\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&lt;\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Implement logic to get the card session from the result of the &lt;code&gt;CardSession.create&lt;\/code&gt; method.&lt;\/p&gt;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Handle the result of the CardSession.create method&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;kotlin\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;val cardSession = when (result) {\\\\n    is CardSessionCreateResult.Success -&amp;gt; result.session\\\\n    else -&amp;gt; throw IllegalStateException(\\\\\\&quot;Error creating card session: $result\\\\\\&quot;)\\\\n}\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&lt;\/li&gt;\\n&lt;\/ol&gt;\\n&quot;,&quot;altTitle&quot;:&quot;android&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;android&quot;}]\"\n            :should-update-when-url-changes='true'>\n        <\/tabs>\n    <\/div>\n<\/div>\n\n<h2 id=\"reveal-pin\">3. Reveal the PIN<\/h2>\n<p>After you initialize the SDK, you can create a secured session. Start the flow for a secured session by calling the <code>CardSession.revealPin<\/code> SDK method. This method instructs the backend to make a request to our  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/overview\" class=\" external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Session authentication API<\/a>. Then, the SDK method retrieves the session data from the backend and returns it to your application.<\/p>\n<p>To create a secured session:<\/p>\n<ol>\n<li>\n<p>From your application, call the <a href=\"#create-session-instance\">session instance<\/a> that you created. Pass the payment instrument ID as a parameter.<br \/>\nThis calls your token provider, which instructs the backend to retrieve a session token from Adyen.<br \/>\nThe following tabs show examples for iOS and Android.<\/p>\n\n<div id=\"tabnvbKu\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;iOS&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Calling the revealPin method\\u2014Example for iOS&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;swift\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;let pin = try await cardSession.revealPin(\\\\n    paymentInstrumentId: \\\\\\&quot;PI00000000000000000000001\\\\\\&quot;\\\\n)\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&quot;,&quot;altTitle&quot;:&quot;ios&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;ios&quot;},{&quot;title&quot;:&quot;Android&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Calling the revealPin method\\u2014Example for Android&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;kotlin\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;val pinRevealResult = cardSession.revealPin(\\\\n    paymentInstrumentId = \\\\\\&quot;PI00000000000000000000001\\\\\\&quot;\\\\n)\\&quot;}]&#039; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\/code-sample&gt;\\n&lt;\/div&gt;\\n&quot;,&quot;altTitle&quot;:&quot;android&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;android&quot;}]\"\n            :should-update-when-url-changes='true'>\n        <\/tabs>\n    <\/div>\n<\/div>\n\n<\/li>\n<li>\n<p>From your backend, make a POST  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/post\/sessions\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/sessions<\/a> request with the following parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/post\/sessions#request-product\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">product<\/a><\/td>\n<td style=\"text-align: center;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/media\/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Set to <strong>platform<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/post\/sessions#request-policy-resources-type\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">policy.resources.type<\/a><\/td>\n<td style=\"text-align: center;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/media\/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Set to <strong>paymentInstrument<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/post\/sessions#request-policy-resources-type-paymentInstrument-paymentInstrumentId\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">policy.resources.paymentInstrumentId<\/a><\/td>\n<td style=\"text-align: center;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/media\/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The unique identifier of the payment instrument that the session is scoped to.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/post\/sessions#request-policy-roles\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">policy.roles<\/a><\/td>\n<td style=\"text-align: center;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/media\/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">An array of roles that define the allowed operations. Include the <strong>PaymentInstrument: Pin Reveal<\/strong> role.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Create a session to reveal the PIN'\" :id=\"'create-session-pin-reveal'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;curl&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/test.adyen.com\\\/authe\\\/api\\\/v1\\\/sessions \\\\\\n   -H 'x-api-key: YOUR_API_KEY' \\\\\\n   -H 'content-type: application\\\/json' \\\\\\n   -X POST \\\\\\n   -d '{\\n      \\&quot;product\\&quot;: \\&quot;platform\\&quot;,\\n      \\&quot;policy\\&quot;: {\\n         \\&quot;resources\\&quot;: [\\n            {\\n               \\&quot;paymentInstrumentId\\&quot;: \\&quot;PI00000000000000000000001\\&quot;,\\n               \\&quot;type\\&quot;: \\&quot;paymentInstrument\\&quot;\\n            }\\n         ],\\n         \\&quot;roles\\&quot;: [\\n            \\&quot;PaymentInstrument: Pin Reveal\\&quot;\\n         ]\\n      }\\n   }'&quot;},{&quot;language&quot;:&quot;java&quot;,&quot;tabTitle&quot;:&quot;Java&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Java API Library v38.0.0 to latest\\nimport com.adyen.Client;\\nimport com.adyen.Config;\\nimport com.adyen.enums.Environment;\\nimport com.adyen.model.*;\\nimport com.adyen.service.*;\\nimport java.math.*;\\nimport com.adyen.model.sessionauthentication.*;\\nimport java.time.OffsetDateTime;\\nimport java.util.*;\\nimport com.adyen.service.sessionauthentication.*;\\n\\nConfig config = new Config()\\n    .apiKey(\\&quot;YOUR_API_KEY\\&quot;)\\n    .environment(Environment.TEST);\\nClient client = new Client(config);\\n\\n\\\/\\\/ Create the request object(s)\\nResource resource1 = new Resource();\\n\\nPolicy policy = new Policy()\\n  .roles(Arrays.asList(\\&quot;PaymentInstrument: Pin Reveal\\&quot;))\\n  .resources(Arrays.asList(resource1));\\n\\nAuthenticationSessionRequest authenticationSessionRequest = new AuthenticationSessionRequest()\\n  .policy(policy);\\n\\n\\\/\\\/ Send the request\\nSessionAuthenticationApi service = new SessionAuthenticationApi(client);\\nAuthenticationSessionResponse response = service.createAuthenticationSession(authenticationSessionRequest, null);&quot;},{&quot;language&quot;:&quot;php&quot;,&quot;tabTitle&quot;:&quot;PHP&quot;,&quot;content&quot;:&quot;&lt;?php\\n\\\/\\\/ Adyen PHP API Library v30.0.0 to latest\\nuse Adyen\\\\Client;\\nuse Adyen\\\\Environment;\\nuse Adyen\\\\Model\\\\SessionAuthentication\\\\Resource;\\nuse Adyen\\\\Model\\\\SessionAuthentication\\\\Policy;\\nuse Adyen\\\\Model\\\\SessionAuthentication\\\\AuthenticationSessionRequest;\\nuse Adyen\\\\Service\\\\SessionAuthentication\\\\SessionAuthenticationApi;\\n\\n$client = new Client();\\n$client-&gt;setXApiKey(\\&quot;YOUR_API_KEY\\&quot;);\\n$client-&gt;setEnvironment(Environment::TEST);\\n\\n\\n\\\/\\\/ Create the request object(s)\\n$resource1 = new Resource();\\n$resource1;\\n\\n$policy = new Policy();\\n$policy\\n  -&gt;setRoles(array(\\&quot;PaymentInstrument: Pin Reveal\\&quot;))\\n  -&gt;setResources(array($resource1));\\n\\n$authenticationSessionRequest = new AuthenticationSessionRequest();\\n$authenticationSessionRequest\\n  -&gt;setPolicy($policy);\\n\\n\\\/\\\/ Send the request\\n$service = new SessionAuthenticationApi($client);\\n$response = $service-&gt;createAuthenticationSession($authenticationSessionRequest);&quot;},{&quot;language&quot;:&quot;cs&quot;,&quot;tabTitle&quot;:&quot;C#&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen .NET API Library v34.0.0 to latest\\nusing System.Collections.Generic;\\nusing Adyen.SessionAuthentication.Extensions;\\nusing Adyen.SessionAuthentication.Models;\\nusing Adyen.SessionAuthentication.Services;\\nusing Adyen.Core.Client;\\nusing Adyen.Core.Client.Extensions;\\nusing Adyen.Core.Options;\\nusing Microsoft.Extensions.DependencyInjection;\\nusing Microsoft.Extensions.Hosting;\\n\\nvar host = Host.CreateDefaultBuilder()\\n    .ConfigureSessionAuthentication(\\n        (context, services, config) =&gt;\\n        {\\n            config.ConfigureAdyenOptions(options =&gt;\\n            {\\n                options.AdyenApiKey = \\&quot;YOUR_API_KEY\\&quot;;\\n                options.Environment = AdyenEnvironment.Test;\\n            });\\n            services.AddAllSessionAuthenticationServices();\\n        })\\n    .Build();\\n\\nvar sessionAuthenticationService = host.Services.GetRequiredService&lt;ISessionAuthenticationService&gt;();\\n\\n\\\/\\\/ Create the request object(s)\\nvar resource1 = new Resource\\n{\\n};\\n\\nvar policy = new Policy\\n{\\n    Roles = new List&lt;string&gt; { \\&quot;PaymentInstrument: Pin Reveal\\&quot; },\\n    Resources = new List&lt;Resource&gt;{ resource1 }\\n};\\n\\nvar authenticationSessionRequest = new AuthenticationSessionRequest\\n{\\n    Policy = policy\\n};\\n\\n\\\/\\\/ Send the request\\nvar result = await sessionAuthenticationService.CreateAuthenticationSessionAsync(authenticationSessionRequest);\\n\\nif (result.TryDeserializeOkResponse(out var response))\\n{\\n    \\\/\\\/ Handle the successful response.\\n}&quot;},{&quot;language&quot;:&quot;js&quot;,&quot;tabTitle&quot;:&quot;NodeJS (JavaScript)&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Node API Library v30.0.0 to latest\\nconst { Client, Config, EnvironmentEnum, SessionAuthenticationAPI } = require('@adyen\\\/api-library');\\n\\nconst config = new Config({\\n  apiKey: \\&quot;YOUR_API_KEY\\&quot;,\\n  environment: EnvironmentEnum.TEST\\n});\\n\\nconst client = new Client(config);\\n\\n\\\/\\\/ Create the request object(s)\\nconst resource1 = {\\n};\\n\\nconst policy = {\\n  roles: [\\&quot;PaymentInstrument: Pin Reveal\\&quot;],\\n  resources: [resource1]\\n};\\n\\nconst authenticationSessionRequest = {\\n  policy: policy\\n};\\n\\n\\\/\\\/ Send the request\\nconst sessionAuthenticationAPI = new SessionAuthenticationAPI(client);\\nconst response = await sessionAuthenticationAPI.SessionAuthenticationApi.createAuthenticationSession(authenticationSessionRequest);&quot;},{&quot;language&quot;:&quot;go&quot;,&quot;tabTitle&quot;:&quot;Go&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Go API Library v21.0.0 to latest\\nimport (\\n  \\&quot;context\\&quot;\\n  \\&quot;github.com\\\/adyen\\\/adyen-go-api-library\\\/v21\\\/src\\\/common\\&quot;\\n  \\&quot;github.com\\\/adyen\\\/adyen-go-api-library\\\/v21\\\/src\\\/adyen\\&quot;\\n  \\&quot;github.com\\\/adyen\\\/adyen-go-api-library\\\/v21\\\/src\\\/sessionauthentication\\&quot;\\n)\\nclient := adyen.NewClient(&amp;common.Config{\\n  ApiKey:      \\&quot;YOUR_API_KEY\\&quot;,\\n  Environment: common.TestEnv,\\n})\\n\\n\\\/\\\/ Create the request object(s)\\nresource1 := sessionauthentication.Resource{\\n}\\n\\npolicy := sessionauthentication.Policy{\\n  Roles: []string{\\n    \\&quot;PaymentInstrument: Pin Reveal\\&quot;,\\n  },\\n  Resources: []sessionauthentication.Resource{\\n      resource1,\\n  },\\n}\\n\\nauthenticationSessionRequest := sessionauthentication.AuthenticationSessionRequest{\\n  Policy: policy,\\n}\\n\\n\\\/\\\/ Send the request\\nservice := client.SessionAuthentication()\\nreq := service.SessionAuthenticationApi.CreateAuthenticationSessionInput().AuthenticationSessionRequest(authenticationSessionRequest)\\nres, httpRes, err := service.SessionAuthenticationApi.CreateAuthenticationSession(context.Background(), req)&quot;},{&quot;language&quot;:&quot;py&quot;,&quot;tabTitle&quot;:&quot;Python&quot;,&quot;content&quot;:&quot;# Adyen Python API Library v14.0.0 to latest\\nimport Adyen\\n\\nadyen = Adyen.Adyen()\\nadyen.client.xapikey = \\&quot;YOUR_API_KEY\\&quot;\\nadyen.client.platform = \\&quot;test\\&quot; # The environment to use library in.\\n\\n# Create the request object(s)\\njson_request = {\\n  \\&quot;product\\&quot;: \\&quot;platform\\&quot;,\\n  \\&quot;policy\\&quot;: {\\n    \\&quot;resources\\&quot;: [{\\n      \\&quot;paymentInstrumentId\\&quot;: \\&quot;PI00000000000000000000001\\&quot;,\\n      \\&quot;type\\&quot;: \\&quot;paymentInstrument\\&quot;\\n    }],\\n    \\&quot;roles\\&quot;: [\\&quot;PaymentInstrument: Pin Reveal\\&quot;]\\n  }\\n}\\n\\n# Send the request\\nresult = adyen.sessionAuthentication.session_authentication_api.create_authentication_session(request=json_request)&quot;},{&quot;language&quot;:&quot;rb&quot;,&quot;tabTitle&quot;:&quot;Ruby&quot;,&quot;content&quot;:&quot;# Adyen Ruby API Library v11.0.0 to latest\\nrequire \\&quot;adyen-ruby-api-library\\&quot;\\n\\nadyen = Adyen::Client.new\\nadyen.api_key = 'YOUR_API_KEY'\\nadyen.env = :test # Set to \\&quot;live\\&quot; for live environment\\n\\n# Create the request object(s)\\nrequest_body = {\\n  \\&quot;product\\&quot; =&gt; \\&quot;platform\\&quot;,\\n  \\&quot;policy\\&quot; =&gt; {\\n    \\&quot;resources\\&quot; =&gt; [{\\n      \\&quot;paymentInstrumentId\\&quot; =&gt; \\&quot;PI00000000000000000000001\\&quot;,\\n      \\&quot;type\\&quot; =&gt; \\&quot;paymentInstrument\\&quot;\\n    }],\\n    \\&quot;roles\\&quot; =&gt; [\\&quot;PaymentInstrument: Pin Reveal\\&quot;]\\n  }\\n}\\n\\n# Send the request\\nresult = adyen.session_authentication.session_authentication_api.create_authentication_session(request_body)&quot;},{&quot;language&quot;:&quot;ts&quot;,&quot;tabTitle&quot;:&quot;NodeJS (TypeScript)&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Node API Library v30.0.0 to latest\\nimport { Client, Config, EnvironmentEnum, SessionAuthenticationAPI, Types } from \\&quot;@adyen\\\/api-library\\&quot;;\\n\\nconst config = new Config({\\n  apiKey: \\&quot;YOUR_API_KEY\\&quot;,\\n  environment: EnvironmentEnum.TEST\\n});\\n\\nconst client = new Client(config);\\n\\n\\\/\\\/ Create the request object(s)\\nconst resource1: Types.sessionAuthentication.Resource = {\\n};\\n\\nconst policy: Types.sessionAuthentication.Policy = {\\n  roles: [\\&quot;PaymentInstrument: Pin Reveal\\&quot;],\\n  resources: [resource1]\\n};\\n\\nconst authenticationSessionRequest = {\\n  policy: policy\\n} as unknown as Types.sessionAuthentication.AuthenticationSessionRequest;\\n\\n\\\/\\\/ Send the request\\nconst sessionAuthenticationAPI = new SessionAuthenticationAPI(client);\\nconst response = await sessionAuthenticationAPI.SessionAuthenticationApi.createAuthenticationSession(authenticationSessionRequest);&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Verify that the response contains a session  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/post\/sessions#responses-200-token\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">token<\/a>.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Session response'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"id\\\": \\\"SESSION_ID\\\",\\n    \\\"token\\\": \\\"SESSION_TOKEN\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Pass the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/post\/sessions#responses-200-token\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">token<\/a> from your backend to the SDK. Use the token provider that you defined when you <a href=\"#create-session-instance\">initialized the SDK<\/a>.<\/p>\n<\/li>\n<\/ol>\n<p>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.<\/p>\n<h2 id=\"show-pin\">4. Show the PIN in your user interface<\/h2>\n<p>After the SDK receives the session token from the backend, the <code>CardSession.revealPin<\/code> method returns a string that includes the decrypted PIN.<\/p>\n<p>To reveal the decrypted PIN in your user interface:<\/p>\n<ol>\n<li>Pass the decrypted PIN to your app.<\/li>\n<li>Reveal the PIN to your cardholder in your user interface.<\/li>\n<\/ol>\n<p>After you reveal the PIN, delete it from your app's memory.<\/p>\n<h2 id=\"troubleshooting\">Troubleshooting<\/h2>\n<p>The following table describes errors the Adyen's SDKs can return and how to solve them.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Error<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<th style=\"text-align: left;\">Solution<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Session expired<\/td>\n<td style=\"text-align: left;\">The session token has expired.<\/td>\n<td style=\"text-align: left;\">Create a new session from your server.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Unauthorized<\/td>\n<td style=\"text-align: left;\">The session does not have the required role for the requested operation.<\/td>\n<td style=\"text-align: left;\"><ul><li markdown=\"1\">Make sure that your API credential has access to the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/sessionauthentication\/latest\/overview\" class=\" external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Session authentication API<\/a>.<\/li><li markdown=\"1\">Make sure that you include the <strong>PaymentInstrument: Pin Reveal<\/strong> role in the request to <a href=\"#reveal-pin\">create the session<\/a>.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Forbidden<\/td>\n<td style=\"text-align: left;\">The payment instrument ID does not match the ID provided in the POST <code>\/sessions<\/code> request.<\/td>\n<td style=\"text-align: left;\">Verify that the payment instrument ID matches the ID provided in the POST <code>\/sessions<\/code> request.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>See also<\/h2>\n<ul>\n<li><a href=\"\/issuing\/manage-card-data\/reveal-pin-ios-sdk\">Reveal PIN with the iOS SDK<\/a><\/li>\n<li><a href=\"\/issuing\/manage-card-data\/reveal-pin\">Reveal PIN with standard encryption<\/a><\/li>\n<\/ul>","url":"https:\/\/docs.adyen.com\/issuing\/manage-card-data\/reveal-pin-sessions","articleFields":{"description":"Allow your cardholders to reveal a PIN using secured sessions with end-to-end encryption.","parameters":{"directoryPath":"\/issuing","sdkRole":"Pin Reveal","sdkMethod":"revealPin","sessionCodeSample":"create-session-pin-reveal"}},"algolia":{"url":"https:\/\/docs.adyen.com\/issuing\/manage-card-data\/reveal-pin-sessions","title":"Reveal a PIN using secured sessions","content":"\nSee our SDKs&nbsp;&nbsp;View the repositories for our SDKs on Github:Adyen Issuing SDK for iOSAdyen Issuing SDK for Android\n\nYou 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.\nThis page explains how to use secured sessions and Adyen's SDKs for iOS and Android to securely reveal PINs in your user interface.\nRequirements\nBefore you begin, take into account the requirements, preparations, and limitations specified in the following tabs.\n\n\n    \n        \n        \n    \n\n\nSecured sessions with Adyen\nWith 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.\nAdyen'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.\nSecured sessions with Adyen's SDKs offers the following benefits:\n\nYour server never handles sensitive PIN data.\nSessions are scoped to a specific card and operation.\nSessions are single-use, which prevents replay attacks.\nEnd-to-end encryption between the SDK and Adyen protects data in transit.\n\nHow it works\nThe following diagram illustrates the PIN reveal flow using sessions.\n\nAs shown in the diagram, the steps for revealing the PIN are:\n\nLoad the application certificate when your application starts.\nCreate a session instance.\nReveal the PIN.\nShow the PIN in your user interface.\n\n1. Load the application certificate\nAdyen 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.\nWhen your application starts:\n\n\nLoad the application certificate into your application.\nThe following tabs show examples of how to load the certificate on each SDK.\n\n\n    \n        \n        \n    \n\n\n\n\n2. Create a session instance\nWhen 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.\nThe following tabs show examples of how to initialize Adyen's SDKs for iOS and Android.\n\n\n    \n        \n        \n    \n\n\n3. Reveal the PIN\nAfter 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. Then, the SDK method retrieves the session data from the backend and returns it to your application.\nTo create a secured session:\n\n\nFrom your application, call the session instance that you created. Pass the payment instrument ID as a parameter.\nThis calls your token provider, which instructs the backend to retrieve a session token from Adyen.\nThe following tabs show examples for iOS and Android.\n\n\n    \n        \n        \n    \n\n\n\n\nFrom your backend, make a POST  \/sessions request with the following parameters:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\n product\n\nSet to platform.\n\n\n policy.resources.type\n\nSet to paymentInstrument.\n\n\n policy.resources.paymentInstrumentId\n\nThe unique identifier of the payment instrument that the session is scoped to.\n\n\n policy.roles\n\nAn array of roles that define the allowed operations. Include the PaymentInstrument: Pin Reveal role.\n\n\n\n\n\n\n\n\nVerify that the response contains a session  token.\n\n\n\n\n\nPass the  token from your backend to the SDK. Use the token provider that you defined when you initialized the SDK.\n\n\nIf 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.\n4. Show the PIN in your user interface\nAfter the SDK receives the session token from the backend, the CardSession.revealPin method returns a string that includes the decrypted PIN.\nTo reveal the decrypted PIN in your user interface:\n\nPass the decrypted PIN to your app.\nReveal the PIN to your cardholder in your user interface.\n\nAfter you reveal the PIN, delete it from your app's memory.\nTroubleshooting\nThe following table describes errors the Adyen's SDKs can return and how to solve them.\n\n\n\nError\nDescription\nSolution\n\n\n\n\nSession expired\nThe session token has expired.\nCreate a new session from your server.\n\n\nUnauthorized\nThe session does not have the required role for the requested operation.\nMake sure that your API credential has access to the  Session authentication API.Make sure that you include the PaymentInstrument: Pin Reveal role in the request to create the session.\n\n\nForbidden\nThe payment instrument ID does not match the ID provided in the POST \/sessions request.\nVerify that the payment instrument ID matches the ID provided in the POST \/sessions request.\n\n\n\nSee also\n\nReveal PIN with the iOS SDK\nReveal PIN with standard encryption\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Adyen Issuing","lvl2":"Manage card data","lvl3":"Reveal a PIN using secured sessions"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/issuing","lvl2":"https:\/\/docs.adyen.com\/issuing\/manage-card-data","lvl3":"\/issuing\/manage-card-data\/reveal-pin-sessions"},"levels":4,"category":"Issuing","category_color":"green","tags":["Reveal","using","secured","sessions"]},"articleFiles":{"create-session-pin-reveal.js":"<p alt=\"\">create-session-pin-reveal.js<\/p>","session-pin-reveal.svg":"<img alt=\"\" src=\"https:\/\/docs.adyen.com\/media\/11aea71a9ca1886db13d388e44375ff82bf9d15d718d2469835768c822496587.svg?decoding=auto&amp;fetchpriority=auto\" \/>"}}
