Classic-integration icon

Custom 3D Secure using a hosted MPI

Adyen is no longer developing the Classic API integration

This page is for the Classic API (/authorise) integration, which we no longer accept new integrations with.

We strongly recommend switching to the newer authorisation-only flow on Checkout API integration.

Step 1: Authorise with the return URL

Submit API payments as a SOAP request using same URL, WSDL, username and password as normal API payments.

  1. Make an /authorise request. 
  2. For custom 3D secure integrations specifically, ensure you pass the following fields:

    • returnUrl: The URL the shopper will be redirected back to after they complete the payment. This URL can have a maximum of 1024 characters.

      Do not add GET parameters to this URL as some custom 3D integrations do not support these. If you want to return dynamic data, for example an order reference, add this as a URL variable.

    • shopperIP: IP address of the shopper.

    • browserInfo.userAgent and browserInfo.acceptHeader: The user agent and accept header value of the shopper's browser. 

These requests and responses are only examples, use a SOAP toolkit to generate actual SOAP requests.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<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>
            <amount xmlns="http://payment.services.adyen.com">
               <currency xmlns="http://common.services.adyen.com">EUR</currency>
               <value xmlns="http://common.services.adyen.com">1000</value>
            </amount>
            <browserInfo xmlns="http://payment.services.adyen.com">
               <acceptHeader xmlns="http://common.services.adyen.com">text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,
image/png,*/*;q=0.5</acceptHeader>
               <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
Firefox/2.0.0.6</userAgent>
            </browserInfo>
            <card xmlns="http://payment.services.adyen.com">
               <cvc>737</cvc>
               <expiryMonth>12</expiryMonth>
               <expiryYear>2012</expiryYear>
               <holderName>T. Est</holderName>
               <number>4111111111111111</number>
            </card>
            <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount>
            <reference xmlns="http://payment.services.adyen.com">YourOrderReference</reference>
            <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP>
            <shopperReference xmlns="http://payment.services.adyen.com">YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j</shopperReference>
            <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
            <additionalData xmlns="http://payment.services.adyen.com">
               <entry>
                  <key xsi:type="xsd:string">returnUrl</key>
                  <value xsi:type="xsd:string">http://www.yourwebsite.com/handle3dresult/YourOrderReference/</value>
               </entry>
            </additionalData>
         </ns1:paymentRequest>
      </ns1:authorise>
   </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<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:authoriseResponse xmlns:ns1="http://payment.services.adyen.com">
         <ns1:paymentResult>
            <additionalData xmlns="http://payment.services.adyen.com">
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.field1</key>
                  <value xsi:type="xsd:string">valueForField1</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.field2</key>
                  <value xsi:type="xsd:string">valueForField2</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.data1</key>
                  <value xsi:type="xsd:string">AABBCCDD</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.data2</key>
                  <value xsi:type="xsd:string">EEFFGGHH</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.otherKey</key>
                  <value xsi:type="xsd:string">0123456789</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">mpiImplementationType</key>
                  <value xsi:type="xsd:string">ACustom3DType</value>
               </entry>
            </additionalData>
            <authCode xmlns="http://payment.services.adyen.com" xsi:nil="true" />
            <dccAmount xmlns="http://payment.services.adyen.com" xsi:nil="true" />
            <dccSignature xmlns="http://payment.services.adyen.com" xsi:nil="true" />
            <fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true" />
            <issuerUrl xmlns="http://payment.services.adyen.com">https://issuerurl.com/do3d/index.php?v=abc</issuerUrl>
            <md xmlns="http://payment.services.adyen.com">bhh............. Q7lYlQ==</md>
            <paRequest xmlns="http://payment.services.adyen.com" xsi:nil="true" />
            <pspReference xmlns="http://payment.services.adyen.com">8313547924770610</pspReference>
            <refusalReason xmlns="http://payment.services.adyen.com" xsi:nil="true" />
            <resultCode xmlns="http://payment.services.adyen.com">RedirectShopper</resultCode>
         </ns1:paymentResult>
      </ns1:authoriseResponse>
   </soap:Body>
</soap:Envelope>

The response will include the following parameters:

  • resultCode If the transaction is refused, for example by Risk, the resultCode will be Refused, and the response should be handled as a normal payment response.

  • issuerUrl: The URL to direct the shopper to.

  • pspReference: The reference for the payment request.

  • md: A payment session identifier returned by the card issuer.

  • additionalData including mpiImplementationType: The merchant plug in implementation type. The value is prefixed with the mpiImplementationType in the format: .. For example, in the example above the mpiImplementationType is ACustom3DType and all additionalData key-value pairs required to redirect the shopper to the issuer include this prefix.

Store the md value from the response in, for example, a database, or the cookie of the shopper. You will submit this value in the authorise3d request after the shopper authenticates and returns to the webshop to complete the payment.

Step 2: Redirect the shopper

If the response to authorisation returns a resultCode with the value RedirectShopper returned in the payment response:

  1. Submit all key-value pairs that are prefixed with the mpiImplementationType using POST to the issuerUrl.
  2. Use a self-submitting form with a fallback in case JavaScript is disabled.

Cut the mpiImplementationType prefix from the keys before they are added to the form. This prefix is only used to identify the fields that must be used for the redirect form.

A sample form with pseudo code/ JSP how to construct the form:

<body onload="document.getElementById('3dform').submit();">
   <form method="POST" action="<%="response.getIssuerUrl()"%>" id="3dform">
      <%
         String mpiImplementation = response.getAdditionalData().get("mpiImplementationType");

         String keyPrefix = mpiImplementation+".";

         for(Map.Entry<String, String> k : response.getAdditionalData().entrySet()) {

         if(k.getKey().startsWith(keyPrefix)) {

         System.out.println("<input type=\"hidden\" name=\""

         + k.getKey().substring(keyPrefix.length())

         + "\" value=\"" + k.getValue() + "\" />");

         }

         }

         %>
      <noscript>
         <br/>
         <br/>
         <div style="text-align: center">
            <h1>Processing your 3-D Secure Transaction </h1>
            <p>Please click continue to continue the processing
               of your 3-D Secure transaction.
            </p>
            <input type="submit" class="button" value="continue"/>
         </div>
      </noscript>
   </form>
</body>

A sample form based on the payment response in step 1:

<body onload="document.getElementById('3dform').submit();">
   <form method="POST" action="https://issuerurl.com/do3d/index.php?v=abc" id="3dform">
      <input type="hidden" name="field1" value="valueForField1" />
      <input type="hidden" name="field2" value="valueForField2" />
      <input type="hidden" name="data1" value="AABBCCDD" />
      <input type="hidden" name="data2" value="EEFFGGHH" />
      <input type="hidden" name="otherKey" value="0123456789" />
      <noscript>
         <br/>
         <br/>
         <div style="text-align: center">
            <h1>Processing your 3-D Secure Transaction </h1>
            <p>Please click continue to continue the processing
               of your 3-D Secure transaction.
            </p>
            <input type="submit" class="button" value="continue"/>
         </div>
      </noscript>
   </form>
</body>

Step 3: Complete the payment

After the shopper authenticates at the issuer, they will be returned to your site through a POST request to the returnUrl sent in the initial /authorise request.

  1. Make an /authorise3d request.
  2. Ensure you include the following fields:

    • merchantAccount: The merchant account to process this payment with. This should be the same as the one used in in the initial /authorise request.

      shopperIP: IP address of the shopper.

    • browserInfo.userAgent and browserInfo.acceptHeader: The user agent and accept header value of the shopper's browser. 

    • additionalData including mpiImplementationType: The merchant plug in implementation type. The value is prefixed with the mpiImplementationType in the format: .. For example, in the example above the mpiImplementationType is ACustom3DType and all additionalData key-value pairs required to redirect the shopper to the issuer include this prefix.

    • md: The value of the md parameter received in the response on the initial authorise request.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<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/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,
image/png,*/*;q=0.5</acceptHeader>
               <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
Firefox/2.0.0.6</userAgent>
            </browserInfo>
            <md xmlns="http://payment.services.adyen.com">bhh.....Q7lYlQ==</md>
            <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount>
            <shopperIP xmlns="http://payment.services.adyen.com">8.8.8.8</shopperIP>
            <additionalData xmlns="http://payment.services.adyen.com">
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.responseKey1</key>
                  <value xsi:type="xsd:string">abcdefgh01</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.responseKey2</key>
                  <value xsi:type="xsd:string">ijklmnop02</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.d1</key>
                  <value xsi:type="xsd:string">DA......TA1</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">ACustom3DType.d2</key>
                  <value xsi:type="xsd:string">DA......TA2</value>
               </entry>
               <entry>
                  <key xsi:type="xsd:string">mpiImplementationType</key>
                  <value xsi:type="xsd:string">ACustom3DType</value>
               </entry>
            </additionalData>
         </ns1:paymentRequest3d>
      </ns1:authorise3d>
   </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<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" xmlns:ns1="http://payment.services.adyen.com">
  <soap:Body>
    <ns1:authorise3dResponse>
      <ns1:paymentResult>
        <ns1:additionalData>
          <ns1:entry>
            <ns1:key xsi:type="xsd:string">cvcResult</ns1:key>
            <ns1:value xsi:type="xsd:string">0 Unknown</ns1:value>
          </ns1:entry>
          <ns1:entry>
            <ns1:key xsi:type="xsd:string">authCode</ns1:key>
            <ns1:value xsi:type="xsd:string">d5ced7026b48537059eda1b190e8e62e4e50ccddfc8cc9d5c9e5813e64630a35</ns1:value>
          </ns1:entry>
          <ns1:entry>
            <ns1:key xsi:type="xsd:string">avsResult</ns1:key>
            <ns1:value xsi:type="xsd:string">0 Unknown</ns1:value>
          </ns1:entry>
          <ns1:entry>
            <ns1:key xsi:type="xsd:string">refusalReasonRaw</ns1:key>
            <ns1:value xsi:type="xsd:string">E000 : No_Error</ns1:value>
          </ns1:entry>
          <ns1:entry>
            <ns1:key xsi:type="xsd:string">acquirerCode</ns1:key>
            <ns1:value xsi:type="xsd:string">AcquirerCodeImplementation</ns1:value>
          </ns1:entry>
        </ns1:additionalData>
        <ns1:pspReference>9915398554833354</ns1:pspReference>
        <ns1:resultCode>Authorised</ns1:resultCode>
        <ns1:authCode>d5ced7026b48537059eda1b190e8e62e4e50ccddfc8cc9d5c9e5813e64630a35</ns1:authCode>
      </ns1:paymentResult>
    </ns1:authorise3dResponse>
  </soap:Body>
</soap:Envelope>