3D Secure 1 and 2 redirect authentication

3D Secure is a protocol provided by credit card schemes. It is an additional authentication protocol that allows you to implement another layer of security on your Card-Not-Present transactions.

During a 3D Secure transaction, the shopper is redirected to a site controlled by the issuing bank to answer additional security questions (usually a unique password or SMS verification). This reduces the chance of a fraudulent transaction occurring.

When 3D Secure is used for personal cards, the chargeback liability shifts to the issuing banks.

Managing PSD2 SCA compliance with 3D Secure

If you are implementing 3D Secure to handle PSD2 compliance, your options are to:

1. Let Adyen handle PSD2 compliance by default.
2. Configure rules using Dynamic 3D Secure.
3. Submit your preference for each transaction in your API request.

In this integration guide, we talk about the steps on how you can submit 3D Secure requests for options 1 and 2.

If you want to use option 3 to send your preference for each transaction in your API request, you will need to submit additional fields. However, note that option 3 overrides our default PSD2 compliance handling logic, including checking if the transaction is out of scope, determining the most suitable exemption type to request for, and evaluating whether to send the exemption in the authentication or authorisation request.

We recommend using option 3 only if you have an extensive knowledge of PSD2 SCA regulations and the 3D Secure protocol.

Requirements

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

• Get an overview of the steps needed to accept live payments.
• Create your test account.

After you have created your test account:

1. Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.
2. Check if 3D Secure 1 is enabled on your account.

Enable 3D Secure

For the test environment, 3D Secure is enabled by default.

For the live environment, it is enabled by default for:

• Bancontact / MisterCash
• Maestro (SecureCode)
• Mastercard (SecureCode)
• Visa (Visa Secure)

Contact the Support Team to configure live 3D Secure transactions for:

• American Express (SafeKey)
• Diners / Discover (ProtectBuy)
• JCB (J/Secure)

Step 1: Authorise the 3D Secure payment

The following example illustrates the /authorise call to initiate a 3D Secure payment.

• Make a POST /authorise request, providing:

  • reference: Your unique reference for this payment.
  • amount

  • card: Object that contains the shopper's card details.

    • number: Encrypted card number.
    • expiryMonth: Encrypted card expiry month.
    • expiryYear: Encrypted card expiry year.
    • cvc: Encrypted card verification code.

    • holderName: Cardholder's name.

      You can only pass raw card data if you are fully PCI compliant. Otherwise, you should use the Client-Side Encryption library to authorise a payment.

  • browserInfo: The shopper's browser information.

  • shopperIP: The shopper's IP address.

    If you are using the redirect authentication for 3D Secure 2, we recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorisation rate. In addition to the regular parameters you provide to Adyen, send additional parameters in this list.

Response

The /authorise response contains a resultCode of either:

• Authorised, or any other resultCodes that you can get for a normal /authorise request. This can happen in case of a frictionless flow (where a liability shift still occurs), or if the card is not enrolled in the 3D Secure program.

• RedirectShopper: Indicates that you need to redirect the shopper to the card issuer for 3D Secure authentication. The response also contains:  

  • paRequest
  • md
  • issuerUrl: URL to where you should redirect the shopper to complete the 3D Secure authentication.

 {
    "additionalData": {
        "paymentMethod": "mc",
        "paymentMethodVariant": "maestro"
    },
    "pspReference": "8535033222809597",
    "resultCode": "RedirectShopper",
    "issuerUrl": "https://issuer-url-here.com",
    "md": "NnheOml4nhgrnx...pP6oBb3KQqKXiYGL3X8=",
    "paRequest": "eNpVUttygjAQ/R...jI+ts3+f4Afk4a3Y"
}

For more information about these fields, refer to PaymentResult.

Step 2: Redirect to the card issuer

If you receive a resultCode RedirectShopper in the /authorise response, you need to redirect the shopper to the card issuer for 3D Secure verification.

You can use an HTML form that you submit with an HTTP POST method call to the URL endpoint specified in issuerUrl. The form should be self-submitting, with a fallback option in case the shopper disabled JavaScript in their web browser. We recommend that you use an HTTPS connection.

In the form, include the following input elements:

• PaReq – corresponds to paRequest and holds the 3D Secure request data for the issuer.
• MD – corresponds to md. A payment session identifier returned by the card issuer. Note that it must be uppercase in the POST message to the issuer.
• TermUrl – corresponds to termUrl. After completing 3D Secure verification on the card issuer site, the shopper is redirected back to the merchant site. This URL value specifies which merchant site page the shopper goes back to. The maximum size is 1024 characters.

The following sample shows an example HTML form:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>Adyen - Create 3D Secure Payment</title>
    </head>
    <body onload="document.getElementById('3dform').submit();">
        <form method="POST" action="${IssuerUrl}" id="3dform">
            <input type="hidden" name="PaReq" value="${PaReq}" />
            <input type="hidden" name="MD" value="${MD}" />
            <input type="hidden" name="TermUrl" value="${TermUrl}" />
            <noscript>
                <br>
                <br>
                <div style="text-align: center">
                    <h1>Processing your 3D Secure Transaction</h1>
                    <p>Please click continue to continue the processing of your 3D Secure transaction.</p>
                    <input type="submit" class="button" value="continue"/>
                </div>
            </noscript>
        </form>
    </body>
</html>

Step 3: Return to the merchant site

After a successful 3D Secure verification, the card issuer redirects the shopper to your website. In this case, you will receive an HTTP POST or GET call to the URL that you specified in TermUrl. We recommend that you use an HTTPS connection.

The HTTP POST or GET call from the card issuer to your URL includes the following parameters:

• MD – A payment session identifier returned by the card issuer.
• PaRes – A payment authorisation response returned by the card issuer.

Pass these parameters in the /authorise3d payment request to Adyen, as shown in the next step.

Step 4: Complete the 3D Secure payment

To complete the 3D Secure authenticated payment, make another request to the /authorise3d endpoint and pass the following parameters with the call:

• merchantAccount – Your merchant account number.
• md – A payment session identifier returned by the card issuer.
• paResponse – Payment authorisation response returned by the card issuer on the previous step.
• shopperIP – We strongly recommend that you provide shopperIP because it is used in a number of risk checks (like location-based and number of payment attempts checks).

The following example demonstrates how to complete the 3D Secure payment:

For information on available fields, refer to API Explorer.

Step 5: Present the payment result

Use the  resultCode from the /authorise or /authorise3d response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a webhook.

For card payments, you can receive the following resultCode values:

Testing 3D Secure payments

Before going live, use the following card numbers and credentials to test your integration.

We recommend testing each Card Type.

To test how your integration handles different 3D Secure 2 authentication scenarios, use our test card numbers.

All our test cards use the following expiry dates and security codes:

When prompted for 3D Secure 2 text challenges, use the following credentials:

• For mobile, use password: 1234
• For web, use password: password

¹ This card doesn't require a CVC.

When you make a payment request with these cards, you'll receive the following result codes depending on your integration:

• RedirectShopper: You'll receive this result code if you are using the Redirect authentication.
• IdentifyShopper: You'll receive this result code if you are using the Native authentication.
• ChallengeShopper: You might get this result code after you submit the 3D Secure 2 device fingerprinting result in a Native authentication, indicating a challenge flow.

To test the web-based flow where the device fingerprinting step is skipped (because the issuer's ACS has not configured a threeDSMethodURL), and you get a ChallengeShopper resultCode immediately after submitting the payment request, use the following card:

To test the frictionless flow, specify in your payment request:

• amount.value: 12002

App-based integration

To test different authentication scenarios for app-based integration, use the following test cards:

Other scenarios

You can check the status of 3D Secure test payments in your Customer Area > Transactions > Payments.