3D Secure

3D Secure (Verified by VisaMastercard SecureCode™) 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.

To use 3D Secure, set up the following:

  • For the test environment, this functionality is enabled by default. 
  • For the live environment, it is enabled by default for Visa/Mastercard/Maestro/BCMC (EU acquiring). In other cases you need to contact the Support Team and request configuring 3D Secure for your account.

Steps to follow:

  1. Authorise the 3D Secure payment
  2. Redirect to the card issuer
  3. Return to the merchant site
  4. Complete the 3D Secure payment

UnionPay requires an additional security layer, see Secure plus to know more.

Authorise the 3D Secure payment

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

  • Using the executeThreeD parameter.
  • Using the browserInfo value, if you have Dynamic 3D Secure configured. 

Request with executeThreeD

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:

{
   "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>

Request with browserInfo

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:

{
  "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>

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

    }
}

(source: Create3dSecurePayment.java)

Response

Then the Adyen system 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: paRequestmdissuerUrl, and 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"
}

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.

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>

(source: create-3d-secure-payment.jsp)

Return to the merchant site

After a successful 3D Secure verification, the issuer redirects the shopper to merchant website using an HTTP POST call to the URL endpoint specified in TermUrl.

The POST call includes the following parameters, which should be used while making an /authorise3d payment call to Adyen to complete the payment transaction:

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

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

{   
    "md" : "31h..........vOXek7w",
    "merchantAccount" : "TestMerchant",
    "paResponse" : "eNqtmF........wGVA4Ch",
    "shopperIP" : "61.294.12.12"
}

<?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:authorise3d xmlns:ns1="http://payment.services.adyen.com">
      <ns1:paymentRequest3d>
         <md xmlns="http://payment.services.adyen.com">31h..........vOXek7w=</md>
         <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
         <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());

    }
}

(source: Authorise3dSecurePayment.java)

For information on available fields, refer to PaymentRequest3d.

Raw 3D Secure responses

Response codes provided by the 3D Secure lookup are the following.

3D Offered

Set to yes if the 3D Secure Protocol if you offer to the cardholder. We explain the raw response in brackets below:

Raw Response Description
Y Enrolled
U Authentication Unavailable
N Not Enrolled (the card is not enrolled for 3D Secure)
N/A Unable to verify

3D Authenticated

The cardholder has successfully authenticated themselves through the 3D Secure Protocol. We explain the raw response in brackets below:

Raw Response Description
Y Authenticated
U Issuer is unable to respond
A Authenticated, enrolled while shopping (First usage of the card in combination with 3D Secure authentication)
N Authentication failed
N/A Unable to verify

SecurePlus

UnionPay requires an additional security layer, SecurePlus, which uses telephone verification.

To use SecurePlus in Ecommerce integration:

  1. Make an /authorise call and include the telephoneNumber field.
  2. If a response contains paRequest set to CUPSecurePlus-CollectSMSVerificationCode, this indicates that a verification code was sent to the provided phone number.
  3. On your web page collect the verification code from the shopper and make an /authorise3d call passing this code as the paResponse field value. In addition, include the  mpiImplementationType field in additionalData and set its value to CUPSecurePlus to indicate that you are making a SecurePlus request.
  4. You get a response with the payment status.

To use SecurePlus in Hosted Payment Pages:

  1. Make an /authorise call including the shopper.telephoneNumber field.
  2. A verification code is sent to the phone number provided by the shopper.
  3. After the shopper enters the code, Adyen processes the payment and sends you a response.

This flow is a part of our Risk Management system, and the authentication may be triggered dynamically based on the risk thresholds set by you.

To enable this feature, contact Support Team.

Questions

Can't find something you are looking for? Look at our FAQ for answers or contact Support.