3D Secure

3D Secure (Verified by VisaMastercard SecureCode™) is an additional authentication protocol that increases security: the shopper is redirected to their card issuer, where they need to authenticate before the payment operation can send an authorisation request.

Set up the following:

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

Ensure that your integration supports:

  1. Making an API call to redirect the shopper to the card issuer.
  2. Submitting a second API call after the redirect to complete the payment.

Steps to follow

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

Redirect to the card issuer

This API call is very similar for non-3D Secure and 3D Secure payment transactions.

3D Secure payments require one additional element: browserInfo.

The browserInfo object is a child element of the paymentRequest main element in a payment request.

browserInfo acts as a container object for the following child elements:

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

"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"
}
<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>
browserInfo.acceptHeader=text%2Fhtml%2Capplication%2Fxhtml%2Bxml%2Capplication%2Fxml%3Bq%3D0.9%2C%2A%2F%2A%3Bq%3D0.8&browserInfo.userAgent=Mozilla%2F5.0+%28X11%3B+Linux+x86_64%29+AppleWebKit%2F537.31+%28KHTML%2C+like+Gecko%29+Chrome%2F26.0.1410.63+Safari%2F537.31

3D Secure directory lookup

After your account is configured for 3D Secure, the Adyen system performs a directory lookup to check if the card is enrolled in the 3D Secure program:

  • If the card is not enrolled, the response is the same as a normal API /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.

Submit 3D Secure lookup response

When a 3D Secure directory lookup confirms that a card is enrolled, you can 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 - It corresponds to paRequest and holds the 3D Secure request data for the issuer.
  • MD - It corresponds to md. A payment session identifier returned by the card issuer.
  • TermUrl - It 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 the merchant site page the shopper goes back to.

Initiate the payment

3D Secure payment request.

{
    "browserInfo" : {
        "acceptHeader" : "text/html,appli.../*;q=0.8",
        "userAgent" : "Mozilla/5.0 ...  Firefox/3.0"
    },
    
    "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>
        <browserInfo xmlns="http://payment.services.adyen.com">
          <acceptHeader xmlns="http://common.services.adyen.com">text/html,appli.../*;q=0.8</acceptHeader>
          <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 ... Firefox/3.0</userAgent>
         </browserInfo>
         <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=' \
--data-urlencode 'browserInfo.acceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
--data-urlencode 'browserInfo.userAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.31 (KHTML, like Gecko) Chrome/26.0.1410.63 Safari/537.31'

See PaymentRequest3d for more info on fields. For more examples, see Other options.

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

Authorise the payment

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

  • merchantAccount - Your merchant account number.
  • browserInfo - A user's browser information.
  • 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).

For more information on these fields, refer to PaymentRequest3d.

SecurePlus

UnionPay requires an additional security layer as SecurePlus using telephone verification.

To use SecurePlus in Ecommerce integration:

  1. Make an /authorise call including the telephoneNumber field.
  2. If a response contains paRequest set to CUPSecurePlus-CollectSMSVerificationCode, this indicates that a verification code is 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 into 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 and the authentication may be triggered dynamically based on the risk thresholds set by you. To enable this feature, contact Adyen Support Team.

Other options

The code below uses the Adyen Java library, which contains all of these APIs to make the integration easier. The library is open-source and available here

Initiate a 3D Secure payment with an 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)

Create a 3D Secure 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());

    }
}

(source: Create3dSecurePayment.java)

Authorise a 3D Secure payment

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)

Questions

Can't find something you are looking for? Look at our FAQ for answers or send an email to support.