---
title: "Custom 3D Secure using a hosted MPI"
url: "https://docs.adyen.com/online-payments/classic-integrations/classic-api-integration/3d-secure-authentication/3d-secure-1/custom-3d-secure-implementation/custom-3d-secure-using-a-hosted-mpi"
source_url: "https://docs.adyen.com/online-payments/classic-integrations/classic-api-integration/3d-secure-authentication/3d-secure-1/custom-3d-secure-implementation/custom-3d-secure-using-a-hosted-mpi.md"
canonical: "https://docs.adyen.com/online-payments/classic-integrations/classic-api-integration/3d-secure-authentication/3d-secure-1/custom-3d-secure-implementation/custom-3d-secure-using-a-hosted-mpi"
last_modified: "2020-05-01T11:34:00+02:00"
language: "en"
---

# Custom 3D Secure using a hosted MPI

[View source](/online-payments/classic-integrations/classic-api-integration/3d-secure-authentication/3d-secure-1/custom-3d-secure-implementation/custom-3d-secure-using-a-hosted-mpi.md)

**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 migrating to the newer [authorisation-only flow on Checkout API](/online-payments/3d-secure/other-3ds-flows/authorize-mpidata) integration. To use this newer integration, you must also [migrate to the Checkout API](/online-payments/upgrade-your-integration/migrate-to-checkout-api).

## 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
<?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
<?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: *..&#xA0;*&#x46;or 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:

```xml
<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:

```xml
<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: *..&#xA0;*&#x46;or example, in the example above the mpiImplementationType is **ACustom3DType&#xA0;**&#x61;nd 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
<?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
<?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>
```