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 authentication webhook.
3. Authenticate the cardholder using the information from the authentication webhook.
4. Finalize the cardholder authentication using the 3D secure challenge ID from the webhook and the SDK output from the authentication step.

Set up and accept authentication webhooks

Your integration must be able to receive and process webhooks for authentication requests.

1. 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. Send the endpoint URL 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
   sdkInput	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
   sdkInput	SCA realm="Challenge" authparm1="{sdkInput}" where sdkInput is a Base64-encoded blob of data to be passed to the SDK in the next step.
   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, specifying the following parameters:

   Parameter	Parameter type	Description
   id	Path	The id value that you receive in the body of the 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

We will notify you of the status and outcome of the authentication after the cardholder has completed 3D Secure authentication. Regardless of whether the authentication process was successfully completed, failed, or expired, 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.