Authenticate cardholders using the Authentication SDK

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.

The following are the steps you need to do to authenticate the cardholder.

1. Set up a webhook endpoint.
2. Get data from the relayed authentication webhook.
3. Authenticate the cardholder using the information from the relayed authentication webhook.
4. Finalize the cardholder authentication using the 3D secure challenge ID from the webhook and the SDK output from the authentication step.
5. Get updates on the outcome of the authentication using the cardholder authenticated webhook.

Set up and accept relayed authentication webhooks

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:

1. You create an endpoint on your server that:

   • Can receive a JSON object.
   • Has an open TCP port for HTTPS traffic on port 443, 8443, or 8843.
   • Can handle basic authentication.

2. You send the endpoint URL to your Adyen contact.

3. Adyen does the following:

   1. If necessary, we enroll your balance platform into ACS.
   2. We subscribe your balance platform to the relayed authentication webhook.
   3. Based on your preference, we prioritize either the out of band (OOB) flow, or the one-time password (OTP) flow.

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

When we send an authentication webhook, your server must respond to the webhook within 2 seconds. Otherwise, the authentication process fails.

To learn more about setting up webhooks, see Set up webhooks.

Get data from the authentication webhooks

When the cardholder makes a transaction that requires authentication, we send a webhook to your server. When you receive the webhook:

The webhook contains the following parameters:

1. From the header and body of the webhook, gather the data that you will need in the following steps of the authentication process.

   The following table shows the header parameter.

   Header parameter	Description
   www-authenticate	SCA realm="Challenge" authparm1="{sdkInput}", where sdkInput is a Base64-encoded blob of data to be passed to the SDK in the next step.

   The following table shows the request body parameters.

   Request body parameter	Description
   id	A unique reference of the 3D Secure challenge.
   paymentInstrumentId	The unique identifier of the payment instrument. Use this field to direct the authentication request to the correct cardholder.
   purchase	An object containing the details of the purchase, such as date, merchant name, and amount.

2. Acknowledge the webhook with the HTTP 200 response that you previously set up.
   The following example shows an HTTP 200 response.

If we do not receive the response message within 2 seconds or receive status set to refused, the authentication process will stop.

For more information about webhook setup and best practices, see Set up webhooks.

Authenticate cardholder

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

After being prompted on the merchant interface, the cardholder proceeds to the application.

Authenticate your cardholder using the SDK. To do so:

1. Trigger the SDK to start cardholder authentication and pass the sdkInput value from the previous step.

2. If the authentication is successful, get the Base64-encoded sdkOutput generated by the SDK.

3. Pass sdkOutput to your server.

In case of any error that occurs at this stage, reach out to your Adyen contact.

Finalize authentication

You must finalize the authentication within 10 minutes of receiving the request. To finalize the authentication:

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

   Parameter	Parameter type	Description
   id	Path	The id value that you receive in the body of the relayed authentication webhook.
   www-authenticate	Header	Set SCA realm to Challenge. Set authparm1 with the Base64-encoded value of sdkOutput from cardholder authentication.
   completed	Body	Set to true.

   The following example shows how to finalize an authentication process.

2. Verify that the response contains the following:

   • The id of the challenge
   • challengeCompleted: true
     This indicates that the cardholder has been authenticated and the transaction will continue.
     Otherwise, refer to Troubleshooting

   The following example shows a response for a finalized authentication.

Get updates

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 balancePlatform.authentication.created webhook.

To keep track of webhooks, make sure that your server can receive and accept webhooks.

The balancePlatform.authentication.created webhook contains the following information.