Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

3D Secure 1 and 2 redirect authentication

Learn how you can support both versions of 3D Secure through a redirect page with your classic API integration.

In this page we describe how you can support both versions of 3D Secure through a redirect. If you want to support 3D Secure 2 natively in your site or in your app, check 3D secure 2 native 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.

While this liability shift is appealing, there is a significant risk of a lower conversion rate when you use 3D Secure. This is because many shoppers are still not familiar with 3D Secure, so may not pass the verification process. Client-side technical errors may also occur when they are redirected.

Adyen has developed a robust dynamic 3D Secure system. This lets you choose which transactions are sent for 3D Secure authentication, and which are processed without. For more information, read Dynamic 3D Secure.

Before you begin

Before you can start accepting 3D Secure 1 authenticated transactions, make sure that you:

  1. Sign up for an Adyen test account at https://www.adyen.com/signup.
  2. Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.
  3. 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 (Verified by Visa)

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

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

UnionPay SecurePlus requires additional configuration, see SecurePlus for more information.

Step 1: Authorise the 3D Secure payment

This documentation explains how to implement 3D Secure with the classic integration. For details on our newer integration, refer to 3D Secure 1 on Online payments API instead.

After your account is configured for 3D Secure, make an /authorise API call. You can request 3D Secure in two ways:

Manual 3D Secure

To manually control whether 3D Secure must be used for the payment transaction, pass the executeThreeD parameter in additionalData. If this parameter is set to true, 3D Secure is initiated; false – 3D Secure is skipped. In addition, we recommend you pass the browserInfo value, which is required for better user experience in a 3D Secure flow.

The following example illustrates the /authorise call to initiate a 3D Secure payment. Note that passing raw card data requires you to be PCI Compliant at Level 1 / Level 2; otherwise, you should use the Client-Side Encryption library to authorise a payment.

{
   "additionalData":{
      "executeThreeD":"true"
   },
   "browserInfo": {
      "userAgent": "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
   },
   "amount":{
      "value":1500,
      "currency":"EUR"
   },
   "card":{
      "number":"5212345678901234",
      "expiryMonth":"8",
      "expiryYear":"2018",
      "cvc":"737",
      "holderName":"John Smith"
   },
   "reference":"payment-3d-2017-9-4-13",
   "merchantAccount":"TestMerchant"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
            <ns1:paymentRequest>
                <additionalData xmlns="http://payment.services.adyen.com">
                    <entry>
                        <key xsi:type="xsd:string">executeThreeD</key>
                        <value xsi:type="xsd:string">true</value>
                    </entry>
                </additionalData>
                <browserInfo xmlns="http://payment.services.adyen.com">
                    <acceptHeader xmlns="http://common.services.adyen.com">text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</acceptHeader>
                    <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0</userAgent>
                </browserInfo>
                <amount xmlns="http://payment.services.adyen.com">
                    <value xmlns="http://common.services.adyen.com">1500</value>
                    <currency xmlns="http://common.services.adyen.com">EUR</currency>
                </amount>
                <card xmlns="http://payment.services.adyen.com">
                    <number>5212345678901234</number>
                    <expiryMonth>8</expiryMonth>
                    <expiryYear>2018</expiryYear>
                    <cvc>737</cvc>
                    <holderName>John Smith</holderName>
                </card>
                <reference xmlns="http://payment.services.adyen.com">payment-3d-2017-9-4-13</reference>
                <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
            </ns1:paymentRequest>
        </ns1:authorise>
    </soap:Body>
</soap:Envelope>

Dynamic 3D Secure

When the executeThreeD parameter is not specified in a payment request, 3D Secure can be initiated depending on the browserInfo parameter value. The browserInfo object acts as a container object for the following child elements:

  • userAgent:  user agent information of the shopper's browser.
  • acceptHeader: holds the Accept header information of the shopper's web browser.

In this case, 3D Secure can be enabled or not depending on your Dynamic 3D Secure settings.

The following example illustrates the /authorise call to initiate Dynamic 3D Secure. Note that passing raw card data requires you to be PCI Compliant at Level 1 / Level 2; otherwise, you should use the Hosting the CSE library library to authorise a payment.

package com.adyen.examples.api.Library; 
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.model.PaymentRequest;
import com.adyen.model.PaymentResult;
import com.adyen.service.Payment;

public class Create3dSecurePayment {

    public void do3dPayment() throws Exception{

        // Create new Client
        Client client = new Client("YourWSUser", "YourWSPassword", Environment.TEST, "myTestPayment");
        Payment payment = new Payment(client);

        // Create new Payment Request
        PaymentRequest paymentRequest= new PaymentRequest();
        paymentRequest.setMerchantAccount("YourMerchantAccount");
        paymentRequest.setReference("YourReference");
        paymentRequest.setBrowserInfoData("YourUserAgent", "YourAcceptHeader");

        // Set Amount
        paymentRequest.setAmountData("123", "EUR");

        // Set 3dCard
        paymentRequest.setCardData("6731012345678906", "John Doe", "08", "2018", "737");

        // Authorise the 3dPayment Request
        PaymentResult paymentResult = payment.authorise(paymentRequest);

        System.out.println("3d Payment Request:");
        System.out.println("- paRequest: " + paymentResult.getPaRequest());
        System.out.println("- md: " + paymentResult.getMd());
        System.out.println("- issuerUrl: " + paymentResult.getIssuerUrl());
        System.out.println("- resultCode: " + paymentResult.getResultCode());

    }
}
{
  "browserInfo": {
     "userAgent": "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0",
     "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
  },
  "card": {
    "number": "5212345678901234",
    "expiryMonth": "8",
    "expiryYear": "2018",
    "cvc": "737",
    "holderName": "John Smith"
  },
  "amount": {
    "value": 1500,
    "currency": "EUR"
  },
  "reference": "payment-3d-2017-9-4-13",
  "merchantAccount": "TestMerchant"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
            <ns1:paymentRequest>
                <browserInfo xmlns="http://payment.services.adyen.com">
                    <acceptHeader xmlns="http://common.services.adyen.com">text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</acceptHeader>
                    <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0</userAgent>
                </browserInfo>
                <amount xmlns="http://payment.services.adyen.com">
                    <value xmlns="http://common.services.adyen.com">1500</value>
                    <currency xmlns="http://common.services.adyen.com">EUR</currency>
                </amount>
                <card xmlns="http://payment.services.adyen.com">
                    <number>5212345678901234</number>
                    <expiryMonth>8</expiryMonth>
                    <expiryYear>2018</expiryYear>
                    <cvc>737</cvc>
                    <holderName>John Smith</holderName>
                </card>
                <reference xmlns="http://payment.services.adyen.com">payment-3d-2017-9-4-13</reference>
                <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
            </ns1:paymentRequest>
        </ns1:authorise>
    </soap:Body>
</soap:Envelope>

Response

Then the Adyen payments platform checks if the card is enrolled in the 3D Secure program:

  • If the card is not enrolled, the response is the same as a normal /authorise call.
  • If the card is enrolled, the response contains the following fields: 

    • paRequest
    • md
    • issuerUrl: URL to where you should redirect the shopper to complete a 3D Secure 1 or 3D Secure 2 authentication.
    • resultCode (which must be set to RedirectShopper). For more information on these fields, refer to PaymentResult.
 {
    "additionalData": {
        "paymentMethod": "mc",
        "paymentMethodVariant": "maestro"
    },
    "pspReference": "8535033222809597",
    "resultCode": "RedirectShopper",
    "issuerUrl": "https://issuer-url-here.com",
    "md": "NnheOml4nhgrnx...pP6oBb3KQqKXiYGL3X8=",
    "paRequest": "eNpVUttygjAQ/R...jI+ts3+f4Afk4a3Y"
}

Step 2: Redirect to the card issuer

When an /authorise response confirms that a card is enrolled in 3D Secure, 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.

If you are implementing this on the web and you prefer to keep the shopper on your checkout page, you can alternatively present the URL in an iframe and then handle the authentication completion.

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.
  • 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 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 call to the URL that you specified in TermUrl. We recommend that you use an HTTPs connection.

The HTTP POST 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 as 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:

curl --user 'user:pass' https://pal-test.adyen.com/pal/servlet/Payment/authorise3d \
--data-urlencode 'merchantAccount=yourMerchantAccount' \
--data-urlencode 'md=d7T...J+xbw==' \
--data-urlencode 'paResponse=eNqtmF....7pqfKo='
package com.adyen.examples.api.Library;

import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.service.Payment;
import com.adyen.model.PaymentRequest3d;
import com.adyen.model.BrowserInfo;
import com.adyen.model.Amount;

public class Authorise3dSecurePayment {

    public void authorise3dPayment() throws Exception {

        // Create new Client
        Client client = new Client("YourWSUser", "YourWSPassword", Environment.TEST, "myTestPayment");
        Payment payment = new Payment(client);

        // Create new 3d Payment Request
        PaymentRequest3d paymentRequest3d = new PaymentRequest3d();

        // Set Browser Info
        BrowserInfo browserInfo = new BrowserInfo();
        browserInfo.setUserAgent("YourUserAgent");
        browserInfo.setAcceptHeader("YourAcceptHeader");

        // Set 3d Payment Request
        paymentRequest3d.setMerchantAccount("YourMerchantAccount");
        paymentRequest3d.setBrowserInfo(browserInfo);
        paymentRequest3d.set3DRequestData("YourMD","YourPaResponse");
        paymentRequest3d.setShopperIP("1.2.3.4");
        PaymentResult paymentResult = payment.authorise3D(paymentRequest3d);

        System.out.println("Payment Result:");
        System.out.println("- pspReference: " + paymentResult.getPspReference());
        System.out.println("- resultCode: " + paymentResult.getResultCode());
        System.out.println("- authCode: " + paymentResult.getAuthCode());
        System.out.println("- refusalReason: " + paymentResult.getRefusalReason());

    }
}
{  
  "merchantAccount":"TestMerchant",
  "md":"31h..........vOXek7w",
  "paResponse":"eNqtmF........wGVA4Ch",
  "shopperIP":"61.294.12.12"
}
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:authorise3d xmlns:ns1="http://payment.services.adyen.com">
      <ns1:paymentRequest3d>
         <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
         <md xmlns="http://payment.services.adyen.com">31h..........vOXek7w=</md>
         <paResponse xmlns="http://payment.services.adyen.com">eNqtmF........wGVA4Ch</paResponse>
         <shopperIP xmlns="http://payment.services.adyen.com">62.194.82.12</shopperIP>
      </ns1:paymentRequest3d>
    </ns1:authorise3d>
  </soap:Body>
</soap:Envelope>

For information on available fields, refer to PaymentRequest3d.

Testing 3D Secure payments

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

We recommend testing each Card Type.

3D Secure 2 test cards

Use the following test cards along with the amounts in the next table to test 3D Secure 2 authentication scenarios.

Card Type Card Number Expiry Month Expiry Year Security Code (CVC/CVV) When to use this card
Visa 4212 3456 7890 1245 10 2020 737 To test any 3D Secure 2 authentication scenario for Visa.
Mastercard 5212 3456 7890 1242 10 2020 737 To test any 3D Secure 2 authentication scenario for Mastercard.
Visa 4212 3456 7891 0006 10 2020 737 To test the web-based authentication flow where you immediately get a ChallengeShopper resultCode right after the /payments request.

Specific authentication scenario

Amount Authentication scenario
12002 Frictionless
12100 Basic text authentication
12110 Basic single select
12120 Basic multi select
12130 Basic out-of-band (OOB) authentication
12140 HTML OOB authentication
12150 App single select then text authentication

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

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

3D Secure 1 test cards

Card Type Card Number Country Expiry Month Expiry Year Security Code (CVC/CVV)
American Express 3451 7792 5488 348 International 10 2020 7373
International 6731 0123 4567 8906 NL 10 2020 737
JCB 3569 9900 1009 5833 US 10 2020 737
Maestro 6771 8309 9999 1239 GB 10 2020 737
Maestro 6771 8300 0000 0000 006 GB 10 2020 737
Mastercard 5212 3456 7890 1234 JP 10 2020 737
Visa 4212 3456 7890 1237 CA 10 2020 737

When prompted for 3D Secure authentication, use the following credentials:

  • Username: user
  • Password: password

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