{"title":"Authenticate cardholders using the Authentication SDK","category":"default","creationDate":1674831720,"content":"<p>Each time your cardholder makes a transaction that requires 3D Secure, you need to authenticate the cardholder. The authentication time frame is valid for 10 minutes.<\/p>\n<p>The following are the steps you need to do to authenticate the cardholder.<\/p>\n<ol>\n<li><a href=\"#step1-set-up-webhook-endpoint\">Set up a webhook endpoint<\/a>.<\/li>\n<li><a href=\"#step2-receive-auth-webhooks\">Get data from the relayed authentication webhook<\/a>.<\/li>\n<li><a href=\"#step3-auth-authenticate-cardholder\">Authenticate the cardholder<\/a> using the information from the relayed authentication webhook.<\/li>\n<li><a href=\"#step4-finalize-auth\">Finalize the cardholder authentication<\/a> using the 3D secure challenge ID from the webhook and the SDK output from the authentication step.<\/li>\n<li><a href=\"#get-updates\">Get updates<\/a> on the outcome of the authentication using the cardholder authenticated webhook.<\/li>\n<\/ol>\n<h2 id=\"step1-set-up-webhook-endpoint\">Set up and accept relayed authentication webhooks<\/h2>\n<p>Your integration must be able to receive and process webhooks for relayed authentication requests. The flow to set up relayed authentication webhooks is as follows:<\/p>\n<ol>\n<li>\n<p>You create an endpoint on your server that:<\/p>\n<ul>\n<li>Can receive a JSON object.<\/li>\n<li>Has an open TCP port for HTTPS traffic on port <strong>443<\/strong>, <strong>8443<\/strong>, or <strong>8843<\/strong>.<\/li>\n<li>Can handle basic authentication.<\/li>\n<\/ul>\n<\/li>\n<li>\n<p>You send the endpoint URL to your Adyen contact.<\/p>\n<\/li>\n<li>\n<p>Adyen does the following:<\/p>\n<ol>\n<li>If necessary, we enroll your balance platform into <a href=\"\/pt\/get-started-with-adyen\/adyen-glossary\/#access-control-server-acs\">ACS<\/a>.<\/li>\n<li>We subscribe your balance platform to the relayed authentication webhook.<\/li>\n<li>Based on your preference, we prioritize either the <a href=\"\/pt\/issuing\/3d-secure\/oob-auth-sdk\/\">out of band (OOB)<\/a> flow, or the <a href=\"\/pt\/issuing\/3d-secure\/password-otp\/\">one-time password (OTP)<\/a> flow.<\/li>\n<\/ol>\n<\/li>\n<li>\n<p>Adyen creates a ws user for your balance platform, and shares its basic auth credentials with you. You can use these credentials to access ACS. If you want to change your basic auth credentials, you must reach out to your Adyen contact.<\/p>\n<\/li>\n<\/ol>\n<p>When we send an authentication webhook, your server must respond to the webhook within 2 seconds. Otherwise, the authentication process fails.<\/p>\n<p>To learn more about setting up webhooks, see <a href=\"\/pt\/development-resources\/webhooks\/configure-and-manage\">Set up webhooks<\/a>.<\/p>\n<h2 id=\"step2-receive-auth-webhooks\">Get data from the authentication webhooks<\/h2>\n<p>When the cardholder makes a transaction that requires authentication, we send a webhook to your server. When you receive the webhook:<\/p>\n<p>The webhook contains the following parameters:<\/p>\n<ol>\n<li>\n<p>From the header and body of the webhook, gather the data that you will need in the following steps of the authentication process.<\/p>\n<p>The following table shows the header parameter.<\/p>\n<table>\n<thead>\n<tr>\n<th>Header parameter<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>www-authenticate<\/code><\/td>\n<td><span translate=\"no\"><strong>SCA realm=\"Challenge\" authparm1=\"{sdkInput}\"<\/strong><\/span>, where <code>sdkInput<\/code> is a Base64-encoded blob of data to be passed to the SDK in the <a href=\"#step3-auth-authenticate-cardholder\">next step<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Authentication webhook header'\" :id=\"''\" :code-data='[{\"language\":\"bash\",\"tabTitle\":\"\",\"content\":\"WWW-authenticate: SCA realm=\\\"Challenge\\\" authparm1=\\\"{sdkInput}\\\"\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>The following table shows the request body parameters.<\/p>\n<table>\n<thead>\n<tr>\n<th>Request body parameter<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>id<\/code><\/td>\n<td>A unique reference of the 3D Secure challenge.<\/td>\n<\/tr>\n<tr>\n<td><code>paymentInstrumentId<\/code><\/td>\n<td>The unique identifier of the payment instrument. Use this field to direct the authentication request to the correct cardholder.<\/td>\n<\/tr>\n<tr>\n<td><code>purchase<\/code><\/td>\n<td>An object containing the details of the purchase, such as date, merchant name, and amount.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Authentication webhook body'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"id\\\": \\\"778a7bd0-0f08-4d0b-b6ec-76c3a47f775c\\\",\\n    \\\"paymentInstrumentId\\\": \\\"PI3227J223222B5F3FXD4B5MJ\\\",\\n    \\\"purchase\\\": {\\n        \\\"date\\\": \\\"2022-06-22T08:00:00.000000+02:00\\\",\\n        \\\"merchantName\\\": \\\"Merchant\\\",\\n        \\\"originalAmount\\\": {\\n            \\\"value\\\": 1000,\\n            \\\"currency\\\": \\\"EUR\\\"\\n        }\\n    }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Acknowledge the webhook with the <span translate=\"no\"><strong>HTTP 200<\/strong><\/span> response that you previously <a href=\"#step1-set-up-webhook-endpoint\">set up<\/a>.<br \/>\nThe following example shows an <span translate=\"no\"><strong>HTTP 200<\/strong><\/span> response.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Acknowledge the webhook'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"authenticationDecision\\\": {\\n        \\\"status\\\": \\\"proceed\\\"\\n    }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<\/ol>\n<p>If we do not receive the response message within 2 seconds or receive <code>status<\/code> set to <span translate=\"no\"><strong>refused<\/strong><\/span>, the authentication process will stop.<\/p>\n<p>For more information about webhook setup and best practices, see <a href=\"\/pt\/development-resources\/webhooks\/configure-and-manage\">Set up webhooks<\/a>.<\/p>\n<h2 id=\"step3-auth-authenticate-cardholder\">Authenticate cardholder<\/h2>\n<p>Your application must display the <a href=\"#step2-receive-auth-webhooks\">data from the previous step<\/a> to the cardholder during the authentication. We recommend that you implement a push notification and use the data from the webhook to inform the cardholder about the details of the transaction they are authenticating for.<\/p>\n<p>After being prompted on the merchant interface, the cardholder proceeds to the application.<\/p>\n<p>Authenticate your cardholder using the SDK. To do so:<\/p>\n<ol>\n<li>\n<p>Trigger the SDK to start cardholder authentication and pass the <code>sdkInput<\/code> value from the previous step.<\/p>\n\n<div id=\"tabLtHqm\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;Kotlin&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Authenticate cardholder using the SDK&#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;lifecycleScope.launch {\\\\n    if (adyenAuthentication.hasCredential(\\\\\\&quot;sdkInput\\\\\\&quot;)) {\\\\n        \\\\\\\/\\\\\\\/ Authenticate existing credential\\\\n        val authenticationResult: AuthenticationResult = adyenAuthentication.authenticate(\\\\\\&quot;sdkInput\\\\\\&quot;)\\\\n        when (authenticationResult) {\\\\n            is AuthenticationResult.AuthenticationSuccessful -&amp;gt; {\\\\n                authenticationResult.sdkOutput\\\\n            }\\\\n            is AuthenticationResult.Canceled -&amp;gt; {\\\\n                \\\\\\\/\\\\\\\/ Cardholder cancelled the authentication flow\\\\n            }\\\\n            is AuthenticationResult.Error -&amp;gt; {\\\\n                \\\\\\\/\\\\\\\/ Unexpected error\\\\n                authenticationResult.errorMessage\\\\n            }\\\\n            is AuthenticationResult.AuthenticationError -&amp;gt; {\\\\n                \\\\\\\/\\\\\\\/ FIDO API Error\\\\n                authenticationResult.authenticationError\\\\n            }\\\\n        }\\\\n    } else {\\\\n        \\\\\\\/\\\\\\\/ None of the known credentials exist in this device\\\\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&quot;,&quot;altTitle&quot;:&quot;kotlin&quot;,&quot;oldTabId&quot;:&quot;authenticate-cardholder-kotlin_1&quot;,&quot;relation&quot;:&quot;kotlin&quot;},{&quot;title&quot;:&quot;Swift&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Authenticate cardholder using the SDK&#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;delegatedAuthenticationSession.authenticate(withBase64URLString: sdkInput) { [weak self] result in\\\\n    switch result {\\\\n    case let .success(sdkOutput):\\\\n        \\\\\\\/\\\\\\\/\\\\\\\/ send the sdkOutput to the backend\\\\n    case let .failure(error):\\\\n        \\\\\\\/\\\\\\\/\\\\\\\/ authentication failed\\\\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&quot;,&quot;altTitle&quot;:&quot;swift&quot;,&quot;oldTabId&quot;:&quot;authenticate-cardholder-swift_2&quot;,&quot;relation&quot;:&quot;swift&quot;}]\"\n            :should-update-when-url-changes='true'>\n        <\/tabs>\n    <\/div>\n<\/div>\n\n<\/li>\n<li>\n<p>If the authentication is successful, get the Base64-encoded <code>sdkOutput<\/code> generated by the SDK.<\/p>\n<\/li>\n<li>\n<p>Pass <code>sdkOutput<\/code> to your server.<\/p>\n<\/li>\n<\/ol>\n<p>In case of any error that occurs at this stage, reach out to your Adyen contact.<\/p>\n<h2 id=\"step4-finalize-auth\">Finalize authentication<\/h2>\n<p>You must finalize the authentication within 10 minutes of receiving the request. To finalize the authentication:<\/p>\n<ol>\n<li>\n<p>From your server, make a PATCH <code>\/challenges<\/code> request. Use the basic auth credentials you received from Adyen when you <a href=\"#set-up-and-accept-relayed-authentication-webhooks\">set up the relayed authentication webhook<\/a>. In your request, specify the following parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th>Parameter<\/th>\n<th style=\"text-align: center;\">Parameter type<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>id<\/code><\/td>\n<td style=\"text-align: center;\">Path<\/td>\n<td>The <code>id<\/code> value that you receive in the body of the relayed <a href=\"#step2-receive-auth-webhooks\">authentication webhook<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>www-authenticate<\/code><\/td>\n<td style=\"text-align: center;\">Header<\/td>\n<td>Set <code>SCA realm<\/code> to <span translate=\"no\"><strong>Challenge<\/strong><\/span>. Set <code>authparm1<\/code> with the Base64-encoded value of <span translate=\"no\"><strong>sdkOutput<\/strong><\/span> from <a href=\"#step3-auth-authenticate-cardholder\">cardholder authentication<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>completed<\/code><\/td>\n<td style=\"text-align: center;\">Body<\/td>\n<td>Set to <span translate=\"no\"><strong>true<\/strong><\/span>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>The following example shows how to finalize an authentication process.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Finalize authentication'\" :id=\"''\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/balanceplatform-api-live.adyen.com\\\/acs\\\/v1\\\/challenges\\\/{id} \\\\\\n-H 'Authorization: ACS_BASIC_AUTH_CREDENTIALS' \\\\\\n-H 'content-type: application\\\/json' \\\\\\n-H \\&quot;www-authenticate: SCA realm=\\&quot;Challenge\\&quot; authparm1=\\&quot;eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNlQzF...\\&quot;\\&quot; \\\\\\n-X PATCH \\\\\\n-d '{\\n    \\&quot;completed\\&quot;: true\\n}'&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 the following:<\/p>\n<ul>\n<li>The <code>id<\/code> of the challenge<\/li>\n<li><code>challengeCompleted<\/code>: <span translate=\"no\"><strong>true<\/strong><\/span><br \/>\nThis indicates that the cardholder has been authenticated and the transaction will continue.<br \/>\nOtherwise, refer to <a href=\"\/pt\/issuing\/3d-secure\/troubleshooting\">Troubleshooting<\/a><\/li>\n<\/ul>\n<p>The following example shows a response for a finalized authentication.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Response for a finalized authentication'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"id\\\": \\\"778a7bd0-0f08-4d0b-b6ec-76c3a47f775c\\\",\\n    \\\"challengeCompleted\\\": true\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<\/ol>\n<h2>Get updates<\/h2>\n<p>You can use the cardholder authenticated webhook to get notified about the status and outcome of the cardholder's 3D secure authentication. Regardless of outcome of the authentication process, we send the <a href=\"https:\/\/docs.adyen.com\/api-explorer\/acs-webhook\/latest\/post\/balancePlatform.authentication.created\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">balancePlatform.authentication.created<\/a>\u00a0webhook.<\/p>\n<p>To keep track of webhooks, make sure that your server can <a href=\"\/pt\/development-resources\/webhooks\/configure-and-manage\">receive and accept webhooks<\/a>.<\/p>\n<p>The <a href=\"https:\/\/docs.adyen.com\/api-explorer\/acs-webhook\/latest\/post\/balancePlatform.authentication.created\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">balancePlatform.authentication.created<\/a> webhook contains the following information.<\/p>\n\n<div id=\"tab1BCTa\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;Authenticated (frictionless flow)&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n    &lt;code-sample :title=\\&quot;&#039;Successful authentication via the frictionless flow&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;json\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;{\\\\n  \\\\\\&quot;data\\\\\\&quot;: {\\\\n    \\\\\\&quot;authentication\\\\\\&quot;: {\\\\n      \\\\\\&quot;acsTransID\\\\\\&quot;: \\\\\\&quot;6a4c1709-a42e-4c7f-96c7-1043adacfc97\\\\\\&quot;,\\\\n      \\\\\\&quot;challengeIndicator\\\\\\&quot;: \\\\\\&quot;01\\\\\\&quot;,\\\\n      \\\\\\&quot;createdAt\\\\\\&quot;: \\\\\\&quot;2022-12-22T15:45:03+01:00\\\\\\&quot;,\\\\n      \\\\\\&quot;deviceChannel\\\\\\&quot;: \\\\\\&quot;app\\\\\\&quot;,\\\\n      \\\\\\&quot;dsTransID\\\\\\&quot;: \\\\\\&quot;a3b86754-444d-46ca-95a2-ada351d3f42c\\\\\\&quot;,\\\\n      \\\\\\&quot;exemptionIndicator\\\\\\&quot;: \\\\\\&quot;lowValue\\\\\\&quot;,\\\\n      \\\\\\&quot;inPSD2scope\\\\\\&quot;: true,\\\\n      \\\\\\&quot;messageCategory\\\\\\&quot;: \\\\\\&quot;payment\\\\\\&quot;,\\\\n      \\\\\\&quot;messageVersion\\\\\\&quot;: \\\\\\&quot;2.2.0\\\\\\&quot;,\\\\n      \\\\\\&quot;riskScore\\\\\\&quot;: 0,\\\\n      \\\\\\&quot;threeDSServerTransID\\\\\\&quot;: \\\\\\&quot;6edcc246-23ee-4e94-ac5d-8ae620bea7d9\\\\\\&quot;,\\\\n      \\\\\\&quot;transStatus\\\\\\&quot;: \\\\\\&quot;Y\\\\\\&quot;,\\\\n      \\\\\\&quot;type\\\\\\&quot;: \\\\\\&quot;frictionless\\\\\\&quot;\\\\n    },\\\\n    \\\\\\&quot;balancePlatform\\\\\\&quot;: \\\\\\&quot;YOUR_BALANCE_PLATFORM\\\\\\&quot;,\\\\n    \\\\\\&quot;id\\\\\\&quot;: \\\\\\&quot;497f6eca-6276-4993-bfeb-53cbbbba6f08\\\\\\&quot;,\\\\n    \\\\\\&quot;paymentInstrumentId\\\\\\&quot;: \\\\\\&quot;PI3227C223222B5BPCMFXD2XG\\\\\\&quot;,\\\\n    \\\\\\&quot;purchase\\\\\\&quot;: {\\\\n      \\\\\\&quot;date\\\\\\&quot;: \\\\\\&quot;2022-12-22T15:49:03+01:00\\\\\\&quot;,\\\\n      \\\\\\&quot;merchantName\\\\\\&quot;: \\\\\\&quot;TeaShop_NL\\\\\\&quot;,\\\\n      \\\\\\&quot;originalAmount\\\\\\&quot;: {\\\\n        \\\\\\&quot;currency\\\\\\&quot;: \\\\\\&quot;EUR\\\\\\&quot;,\\\\n        \\\\\\&quot;value\\\\\\&quot;: 1000\\\\n      }\\\\n    },\\\\n    \\\\\\&quot;status\\\\\\&quot;: \\\\\\&quot;authenticated\\\\\\&quot;\\\\n  },\\\\n  \\\\\\&quot;environment\\\\\\&quot;: \\\\\\&quot;test\\\\\\&quot;,\\\\n  \\\\\\&quot;type\\\\\\&quot;: \\\\\\&quot;balancePlatform.authentication.created\\\\\\&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;:null,&quot;oldTabId&quot;:&quot;authenticated_(frictionless_flow)_0_1&quot;,&quot;relation&quot;:&quot;&quot;},{&quot;title&quot;:&quot;Authenticated (challenge flow)&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n    &lt;code-sample :title=\\&quot;&#039;Successful authentication via the challenge flow&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;json\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;{\\\\n  \\\\\\&quot;data\\\\\\&quot;: {\\\\n    \\\\\\&quot;authentication\\\\\\&quot;: {\\\\n      \\\\\\&quot;acsTransID\\\\\\&quot;: \\\\\\&quot;6a4c1709-a42e-4c7f-96c7-1043adacfc97\\\\\\&quot;,\\\\n      \\\\\\&quot;challenge\\\\\\&quot;: {\\\\n        \\\\\\&quot;flow\\\\\\&quot;: \\\\\\&quot;OOB\\\\\\&quot;,\\\\n        \\\\\\&quot;lastInteraction\\\\\\&quot;: \\\\\\&quot;2022-12-22T15:49:03+01:00\\\\\\&quot;\\\\n      },\\\\n      \\\\\\&quot;challengeIndicator\\\\\\&quot;: \\\\\\&quot;01\\\\\\&quot;,\\\\n      \\\\\\&quot;createdAt\\\\\\&quot;: \\\\\\&quot;2022-12-22T15:45:03+01:00\\\\\\&quot;,\\\\n      \\\\\\&quot;deviceChannel\\\\\\&quot;: \\\\\\&quot;app\\\\\\&quot;,\\\\n      \\\\\\&quot;dsTransID\\\\\\&quot;: \\\\\\&quot;a3b86754-444d-46ca-95a2-ada351d3f42c\\\\\\&quot;,\\\\n      \\\\\\&quot;exemptionIndicator\\\\\\&quot;: \\\\\\&quot;lowValue\\\\\\&quot;,\\\\n      \\\\\\&quot;inPSD2scope\\\\\\&quot;: true,\\\\n      \\\\\\&quot;messageCategory\\\\\\&quot;: \\\\\\&quot;payment\\\\\\&quot;,\\\\n      \\\\\\&quot;messageVersion\\\\\\&quot;: \\\\\\&quot;2.2.0\\\\\\&quot;,\\\\n      \\\\\\&quot;riskScore\\\\\\&quot;: 0,\\\\n      \\\\\\&quot;threeDSServerTransID\\\\\\&quot;: \\\\\\&quot;6edcc246-23ee-4e94-ac5d-8ae620bea7d9\\\\\\&quot;,\\\\n      \\\\\\&quot;transStatus\\\\\\&quot;: \\\\\\&quot;Y\\\\\\&quot;,\\\\n      \\\\\\&quot;type\\\\\\&quot;: \\\\\\&quot;challenge\\\\\\&quot;\\\\n    },\\\\n    \\\\\\&quot;balancePlatform\\\\\\&quot;: \\\\\\&quot;YOUR_BALANCE_PLATFORM\\\\\\&quot;,\\\\n    \\\\\\&quot;id\\\\\\&quot;: \\\\\\&quot;497f6eca-6276-4993-bfeb-53cbbbba6f08\\\\\\&quot;,\\\\n    \\\\\\&quot;paymentInstrumentId\\\\\\&quot;: \\\\\\&quot;PI3227C223222B5BPCMFXD2XG\\\\\\&quot;,\\\\n    \\\\\\&quot;purchase\\\\\\&quot;: {\\\\n      \\\\\\&quot;date\\\\\\&quot;: \\\\\\&quot;2022-12-22T15:49:03+01:00\\\\\\&quot;,\\\\n      \\\\\\&quot;merchantName\\\\\\&quot;: \\\\\\&quot;TeaShop_NL\\\\\\&quot;,\\\\n      \\\\\\&quot;originalAmount\\\\\\&quot;: {\\\\n        \\\\\\&quot;currency\\\\\\&quot;: \\\\\\&quot;EUR\\\\\\&quot;,\\\\n        \\\\\\&quot;value\\\\\\&quot;: 1000\\\\n      }\\\\n    },\\\\n    \\\\\\&quot;status\\\\\\&quot;: \\\\\\&quot;authenticated\\\\\\&quot;\\\\n  },\\\\n  \\\\\\&quot;environment\\\\\\&quot;: \\\\\\&quot;test\\\\\\&quot;,\\\\n  \\\\\\&quot;type\\\\\\&quot;: \\\\\\&quot;balancePlatform.authentication.created\\\\\\&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;:null,&quot;oldTabId&quot;:&quot;authenticated_(challenge_flow)_1_2&quot;,&quot;relation&quot;:&quot;&quot;},{&quot;title&quot;:&quot;Rejected (retries exceeded)&quot;,&quot;content&quot;:&quot;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n    &lt;code-sample :title=\\&quot;&#039;Rejected authentication due to exceeded number of retries&#039;\\&quot; :id=\\&quot;&#039;&#039;\\&quot; :code-data=&#039;[{\\&quot;language\\&quot;:\\&quot;json\\&quot;,\\&quot;tabTitle\\&quot;:\\&quot;\\&quot;,\\&quot;content\\&quot;:\\&quot;{\\\\n  \\\\\\&quot;data\\\\\\&quot;: {\\\\n    \\\\\\&quot;balancePlatform\\\\\\&quot;: \\\\\\&quot;YOUR_BALANCE_PLATFORM\\\\\\&quot;,\\\\n    \\\\\\&quot;creationDate\\\\\\&quot;: \\\\\\&quot;2023-01-19T17:07:59+01:00\\\\\\&quot;,\\\\n    \\\\\\&quot;id\\\\\\&quot;: \\\\\\&quot;a8fc7a40-6e48-498a-bdc2-494daf0f490a\\\\\\&quot;,\\\\n    \\\\\\&quot;authentication\\\\\\&quot;: {\\\\n      \\\\\\&quot;acsTransId\\\\\\&quot;: \\\\\\&quot;a8fc7a40-6e48-498a-bdc2-494daf0f490a\\\\\\&quot;,\\\\n      \\\\\\&quot;challenge\\\\\\&quot;: {\\\\n        \\\\\\&quot;flow\\\\\\&quot;: \\\\\\&quot;OTP_SMS\\\\\\&quot;,\\\\n        \\\\\\&quot;lastInteraction\\\\\\&quot; : \\\\\\&quot;2023-01-19T17:37:13+01:00\\\\\\&quot;,\\\\n        \\\\\\&quot;phoneNumber\\\\\\&quot; : \\\\\\&quot;******6789\\\\\\&quot;,\\\\n        \\\\\\&quot;resends\\\\\\&quot; : 0,\\\\n        \\\\\\&quot;retries\\\\\\&quot; : 2\\\\n      },\\\\n      \\\\\\&quot;challengeIndicator\\\\\\&quot;: \\\\\\&quot;01\\\\\\&quot;,\\\\n      \\\\\\&quot;createdAt\\\\\\&quot;: \\\\\\&quot;2023-01-19T17:07:17+01:00\\\\\\&quot;,\\\\n      \\\\\\&quot;deviceChannel\\\\\\&quot;: \\\\\\&quot;app\\\\\\&quot;,\\\\n      \\\\\\&quot;dsTransID\\\\\\&quot;: \\\\\\&quot;59de4e30-7f84-4a77-aaf8-1ca493092ef9\\\\\\&quot;,\\\\n      \\\\\\&quot;exemptionIndicator\\\\\\&quot;: \\\\\\&quot;noExemptionApplied\\\\\\&quot;,\\\\n      \\\\\\&quot;inPSD2Scope\\\\\\&quot;: \\\\\\&quot;false\\\\\\&quot;,\\\\n      \\\\\\&quot;messageCategory\\\\\\&quot;: \\\\\\&quot;payment\\\\\\&quot;,\\\\n      \\\\\\&quot;messageVersion\\\\\\&quot;: \\\\\\&quot;2.2.0\\\\\\&quot;,\\\\n      \\\\\\&quot;threeDSServerTransID\\\\\\&quot;: \\\\\\&quot;8bc0fdbd-5c8a-4bed-a171-9d10347e7798\\\\\\&quot;,\\\\n      \\\\\\&quot;transStatus\\\\\\&quot;: \\\\\\&quot;N\\\\\\&quot;,\\\\n      \\\\\\&quot;transStatusReason\\\\\\&quot;: \\\\\\&quot;19\\\\\\&quot;,\\\\n      \\\\\\&quot;type\\\\\\&quot;: \\\\\\&quot;challenge\\\\\\&quot;\\\\n    },\\\\n    \\\\\\&quot;paymentInstrumentId\\\\\\&quot;: \\\\\\&quot;PI3227C223222B5BPCMFXD2XG\\\\\\&quot;,\\\\n    \\\\\\&quot;purchase\\\\\\&quot;: {\\\\n      \\\\\\&quot;date\\\\\\&quot;: \\\\\\&quot;2022-12-22T15:49:03+01:00\\\\\\&quot;,\\\\n      \\\\\\&quot;merchantName\\\\\\&quot;: \\\\\\&quot;TeaShop_NL\\\\\\&quot;,\\\\n      \\\\\\&quot;originalAmount\\\\\\&quot;: {\\\\n        \\\\\\&quot;currency\\\\\\&quot;: \\\\\\&quot;EUR\\\\\\&quot;,\\\\n        \\\\\\&quot;value\\\\\\&quot;: 1000\\\\n      }\\\\n    },\\\\n    \\\\\\&quot;status\\\\\\&quot;: \\\\\\&quot;rejected\\\\\\&quot;\\\\n  },\\\\n  \\\\\\&quot;environment\\\\\\&quot;: \\\\\\&quot;test\\\\\\&quot;,\\\\n  \\\\\\&quot;type\\\\\\&quot;: \\\\\\&quot;balancePlatform.authentication.created\\\\\\&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;:null,&quot;oldTabId&quot;:&quot;rejected_(retries_exceeded)_2_3&quot;,&quot;relation&quot;:&quot;&quot;}]\"\n            :should-update-when-url-changes='false'>\n        <\/tabs>\n    <\/div>\n<\/div>\n","url":"https:\/\/docs.adyen.com\/pt\/issuing\/3d-secure\/oob-auth-sdk\/authenticate-cardholders","articleFields":{"description":"Use our Authentication SDK for out-of-band authentication of payments made with Adyen-issued cards.","feedback_component":true,"type":"page","_expandable":{"operations":""},"status":"current","next_steps_description":"Learn about the payment stages and authorisation in particular.","next_steps":[{"title":"Payment stages","description":"Learn about the payment stages and when funds are added to or deducted from the balance account.","url":"\/issuing\/payment-stages","required":false},{"title":"Payment authorisation","description":"Approve or decline payments by using transaction rules or relayed authorisation.","url":"\/issuing\/authorisation","required":true}],"parameters":{"integrationType":"issuing","directoryPath":"\/issuing"},"last_edit_on":"12-07-2023 13:49","filters_component":false,"page_id":"e5f00fab-7c08-4896-99ba-2ecfd2db2f4d","decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/issuing\/3d-secure\/oob-auth-sdk\/authenticate-cardholders","title":"Authenticate cardholders using the Authentication SDK","content":"Each time your cardholder makes a transaction that requires 3D Secure, you need to authenticate the cardholder. The authentication time frame is valid for 10 minutes.\nThe following are the steps you need to do to authenticate the cardholder.\n\nSet up a webhook endpoint.\nGet data from the relayed authentication webhook.\nAuthenticate the cardholder using the information from the relayed authentication webhook.\nFinalize the cardholder authentication using the 3D secure challenge ID from the webhook and the SDK output from the authentication step.\nGet updates on the outcome of the authentication using the cardholder authenticated webhook.\n\nSet up and accept relayed authentication webhooks\nYour integration must be able to receive and process webhooks for relayed authentication requests. The flow to set up relayed authentication webhooks is as follows:\n\n\nYou create an endpoint on your server that:\n\nCan receive a JSON object.\nHas an open TCP port for HTTPS traffic on port 443, 8443, or 8843.\nCan handle basic authentication.\n\n\n\nYou send the endpoint URL to your Adyen contact.\n\n\nAdyen does the following:\n\nIf necessary, we enroll your balance platform into ACS.\nWe subscribe your balance platform to the relayed authentication webhook.\nBased on your preference, we prioritize either the out of band (OOB) flow, or the one-time password (OTP) flow.\n\n\n\nAdyen creates a ws user for your balance platform, and shares its basic auth credentials with you. You can use these credentials to access ACS. If you want to change your basic auth credentials, you must reach out to your Adyen contact.\n\n\nWhen we send an authentication webhook, your server must respond to the webhook within 2 seconds. Otherwise, the authentication process fails.\nTo learn more about setting up webhooks, see Set up webhooks.\nGet data from the authentication webhooks\nWhen the cardholder makes a transaction that requires authentication, we send a webhook to your server. When you receive the webhook:\nThe webhook contains the following parameters:\n\n\nFrom the header and body of the webhook, gather the data that you will need in the following steps of the authentication process.\nThe following table shows the header parameter.\n\n\n\nHeader parameter\nDescription\n\n\n\n\nwww-authenticate\nSCA realm=\"Challenge\" authparm1=\"{sdkInput}\", where sdkInput is a Base64-encoded blob of data to be passed to the SDK in the next step.\n\n\n\n\n\n\nThe following table shows the request body parameters.\n\n\n\nRequest body parameter\nDescription\n\n\n\n\nid\nA unique reference of the 3D Secure challenge.\n\n\npaymentInstrumentId\nThe unique identifier of the payment instrument. Use this field to direct the authentication request to the correct cardholder.\n\n\npurchase\nAn object containing the details of the purchase, such as date, merchant name, and amount.\n\n\n\n\n\n\n\n\nAcknowledge the webhook with the HTTP 200 response that you previously set up.\nThe following example shows an HTTP 200 response.\n\n\n\n\n\nIf we do not receive the response message within 2 seconds or receive status set to refused, the authentication process will stop.\nFor more information about webhook setup and best practices, see Set up webhooks.\nAuthenticate cardholder\nYour application must display the data from the previous step to the cardholder during the authentication. We recommend that you implement a push notification and use the data from the webhook to inform the cardholder about the details of the transaction they are authenticating for.\nAfter being prompted on the merchant interface, the cardholder proceeds to the application.\nAuthenticate your cardholder using the SDK. To do so:\n\n\nTrigger the SDK to start cardholder authentication and pass the sdkInput value from the previous step.\n\n\n    \n        \n        \n    \n\n\n\n\nIf the authentication is successful, get the Base64-encoded sdkOutput generated by the SDK.\n\n\nPass sdkOutput to your server.\n\n\nIn case of any error that occurs at this stage, reach out to your Adyen contact.\nFinalize authentication\nYou must finalize the authentication within 10 minutes of receiving the request. To finalize the authentication:\n\n\nFrom your server, make a PATCH \/challenges request. Use the basic auth credentials you received from Adyen when you set up the relayed authentication webhook. In your request, specify the following parameters:\n\n\n\nParameter\nParameter type\nDescription\n\n\n\n\nid\nPath\nThe id value that you receive in the body of the relayed authentication webhook.\n\n\nwww-authenticate\nHeader\nSet SCA realm to Challenge. Set authparm1 with the Base64-encoded value of sdkOutput from cardholder authentication.\n\n\ncompleted\nBody\nSet to true.\n\n\n\nThe following example shows how to finalize an authentication process.\n\n\n\n\n\nVerify that the response contains the following:\n\nThe id of the challenge\nchallengeCompleted: true\nThis indicates that the cardholder has been authenticated and the transaction will continue.\nOtherwise, refer to Troubleshooting\n\nThe following example shows a response for a finalized authentication.\n\n\n\n\n\nGet updates\nYou can use the cardholder authenticated webhook to get notified about the status and outcome of the cardholder's 3D secure authentication. Regardless of outcome of the authentication process, we send the balancePlatform.authentication.created\u00a0webhook.\nTo keep track of webhooks, make sure that your server can receive and accept webhooks.\nThe balancePlatform.authentication.created webhook contains the following information.\n\n\n    \n        \n        \n    \n\n","type":"page","locale":"pt","boost":16,"hierarchy":{"lvl0":"Home","lvl1":"Adyen Issuing","lvl2":"Enroll cards in 3D Secure","lvl3":"Using the out-of-band authentication SDK","lvl4":"Authenticate cardholders using the Authentication SDK"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/issuing","lvl2":"https:\/\/docs.adyen.com\/pt\/issuing\/3d-secure","lvl3":"https:\/\/docs.adyen.com\/pt\/issuing\/3d-secure\/oob-auth-sdk","lvl4":"\/pt\/issuing\/3d-secure\/oob-auth-sdk\/authenticate-cardholders"},"levels":5,"category":"Issuing","category_color":"green","tags":["Authenticate","cardholders","using","Authentication"]}}
