Search

Are you looking for test card numbers?

Would you like to contact support?

Classic-integration icon

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.

On this page we describe how you can support both versions of 3D Secure through a redirect. If you have an existing 3D Secure 1 implementation, you can already support 3D Secure 2 on the same redirect.

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.

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.

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.

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 PCI Level 1 or 2 certified. Otherwise, you should use the Client-Side Encryption library to authorise a payment.

    • browserInfo: The shopper's browser information. Providing this is optional but provides a smoother authentication flow for the shopper.
    • 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.

{
   "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":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}
<?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

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.

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

{  
  "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>
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());

    }
}

For information on available fields, refer to API Explorer.

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:

Expiry Date CVC/CVV CID
10/2020 737 7373
03/2030 737 7373

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

  • For mobile, use password: 1234
  • For web, use password: password
Card Type Card Number
American Express 3714 4963 5398 431
Cartes Bancaires 4035 5014 2814 6300
Diners 3056 9309 0259 04
Discover 6011 1111 1111 1117
JCB 3566 1111 1111 1113
Mastercard 5454 5454 5454 5454
UnionPay 6212 3456 7890 1232
Visa 4917 6100 0000 0000

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:

Card Type Card Number
Visa 4212 3456 7891 0006

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:

Card number Authentication scenario
5201 2855 6567 2311 Basic text authentication
5201 2874 9905 2008 Basic single select
5201 2815 9233 1633 Basic multi select
5201 2888 2269 6974 Basic out-of-band (OOB) authentication
5201 2895 0084 3268 HTML OOB authentication
5201 2861 5377 1465 App single select then text authentication

Other scenarios

Card number Scenario
4199 3500 0000 0002 The card is not enrolled for 3D Secure transactions,
5201 2829 9900 5515 There was a technical error.
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

Card not enrolled in 3D Secure 1

To test a scenario where the card is not enrolled for 3D Secure transactions, use the following card:

Card Type Card Number Expiry Date Security Code (CVV2)
Visa 4199 3500 0000 0002 03/2030 737

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