Step 1: 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:

  • Manually initiate 3D Secure using the executeThreeD parameter.
  • Use Dynamic 3D Secure, which can be triggered by passing browserInfo value. 

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.

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