{"title":"Custom 3D Secure using a hosted MPI","category":"default","creationDate":1776961627,"content":"<div class=\"sc-notice warning\"><div>\n<p><strong>Adyen is no longer developing the Classic API integration<\/strong><\/p>\n<p>This page is for the Classic API (<code>\/authorise<\/code>) integration, which we no longer accept new integrations with. <\/p>\n<p>We strongly recommend migrating to the newer <a href=\"\/online-payments\/3d-secure\/other-3ds-flows\/authorize-mpidata\">authorisation-only flow on Checkout API<\/a> integration. To use this newer integration, you must also <a href=\"\/pt\/online-payments\/upgrade-your-integration\/migrate-to-checkout-api\">migrate to the Checkout API<\/a>.<\/p>\n<\/div><\/div>\n<h2 id=\"step-1-authorise-with-the-return-url\">Step 1: Authorise with the return URL<\/h2>\n<p>Submit API payments as a SOAP request using same URL, WSDL, username and password as normal API payments.<\/p>\n<ol>\n<li>Make an\u00a0<code>\/authorise<\/code>\u00a0request.\u00a0<\/li>\n<li>For custom 3D secure integrations specifically, ensure you pass the following fields:<\/li>\n<\/ol>\n<ul>\n<li>\n<ul>\n<li>\n<p><code>returnUrl<\/code>: The URL the shopper will be redirected back to after they complete the payment. This URL can have a maximum of 1024 characters.<\/p>\n<div class=\"sc-notice note\"><div>\n<p>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.<\/p>\n<\/div><\/div>\n<\/li>\n<li>\n<p><code>shopperIP<\/code>: IP address of the shopper.<\/p>\n<\/li>\n<li>\n<p><code>browserInfo.userAgent<\/code>\u00a0and\u00a0<code>browserInfo.acceptHeader<\/code>:\u00a0The user agent and accept header value of the shopper's browser.\u00a0<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<div class=\"sc-notice note\"><div>\n<p>These requests and responses are only examples, use a SOAP toolkit to generate actual SOAP requests.<\/p>\n<\/div><\/div>\n<p>Request:<\/p>\n<pre><code class=\"language-xml\">&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n   &lt;soap:Body&gt;\n      &lt;ns1:authorise xmlns:ns1=\"http:\/\/payment.services.adyen.com\"&gt;\n         &lt;ns1:paymentRequest&gt;\n            &lt;amount xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;currency xmlns=\"http:\/\/common.services.adyen.com\"&gt;EUR&lt;\/currency&gt;\n               &lt;value xmlns=\"http:\/\/common.services.adyen.com\"&gt;1000&lt;\/value&gt;\n            &lt;\/amount&gt;\n            &lt;browserInfo xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;acceptHeader xmlns=\"http:\/\/common.services.adyen.com\"&gt;text\/xml,application\/xml,application\/xhtml+xml,text\/html;q=0.9,text\/plain;q=0.8,\nimage\/png,*\/*;q=0.5&lt;\/acceptHeader&gt;\n               &lt;userAgent xmlns=\"http:\/\/common.services.adyen.com\"&gt;Mozilla\/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko\/20070725\nFirefox\/2.0.0.6&lt;\/userAgent&gt;\n            &lt;\/browserInfo&gt;\n            &lt;card xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;cvc&gt;737&lt;\/cvc&gt;\n               &lt;expiryMonth&gt;12&lt;\/expiryMonth&gt;\n               &lt;expiryYear&gt;2012&lt;\/expiryYear&gt;\n               &lt;holderName&gt;T. Est&lt;\/holderName&gt;\n               &lt;number&gt;4111111111111111&lt;\/number&gt;\n            &lt;\/card&gt;\n            &lt;merchantAccount xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YourMerchant&lt;\/merchantAccount&gt;\n            &lt;reference xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YourOrderReference&lt;\/reference&gt;\n            &lt;shopperIP xmlns=\"http:\/\/payment.services.adyen.com\"&gt;61.294.12.12&lt;\/shopperIP&gt;\n            &lt;shopperReference xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j&lt;\/shopperReference&gt;\n            &lt;shopperEmail xmlns=\"http:\/\/payment.services.adyen.com\"&gt;s.hopper@test.com&lt;\/shopperEmail&gt;\n            &lt;additionalData xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;returnUrl&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;http:\/\/www.yourwebsite.com\/handle3dresult\/YourOrderReference\/&lt;\/value&gt;\n               &lt;\/entry&gt;\n            &lt;\/additionalData&gt;\n         &lt;\/ns1:paymentRequest&gt;\n      &lt;\/ns1:authorise&gt;\n   &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;<\/code><\/pre>\n<p>Response:<\/p>\n<pre><code class=\"language-xml\">&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n   &lt;soap:Body&gt;\n      &lt;ns1:authoriseResponse xmlns:ns1=\"http:\/\/payment.services.adyen.com\"&gt;\n         &lt;ns1:paymentResult&gt;\n            &lt;additionalData xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.field1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;valueForField1&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.field2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;valueForField2&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.data1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;AABBCCDD&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.data2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;EEFFGGHH&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.otherKey&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;0123456789&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;mpiImplementationType&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;ACustom3DType&lt;\/value&gt;\n               &lt;\/entry&gt;\n            &lt;\/additionalData&gt;\n            &lt;authCode xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;dccAmount xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;dccSignature xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;fraudResult xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;issuerUrl xmlns=\"http:\/\/payment.services.adyen.com\"&gt;https:\/\/issuerurl.com\/do3d\/index.php?v=abc&lt;\/issuerUrl&gt;\n            &lt;md xmlns=\"http:\/\/payment.services.adyen.com\"&gt;bhh............. Q7lYlQ==&lt;\/md&gt;\n            &lt;paRequest xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;pspReference xmlns=\"http:\/\/payment.services.adyen.com\"&gt;8313547924770610&lt;\/pspReference&gt;\n            &lt;refusalReason xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;resultCode xmlns=\"http:\/\/payment.services.adyen.com\"&gt;RedirectShopper&lt;\/resultCode&gt;\n         &lt;\/ns1:paymentResult&gt;\n      &lt;\/ns1:authoriseResponse&gt;\n   &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;<\/code><\/pre>\n<p>The response will include the following parameters:<\/p>\n<ul>\n<li>\n<p><code>resultCode<\/code>\u00a0If the transaction is refused, for example by Risk, the <code>resultCode<\/code> will be <strong>Refused<\/strong>, and the response should be handled as a normal payment response.<\/p>\n<\/li>\n<li>\n<p><code>issuerUrl<\/code>: The URL to direct the shopper to.<\/p>\n<\/li>\n<li>\n<p><code>pspReference<\/code>: The reference for the payment request.<\/p>\n<\/li>\n<li>\n<p><code>md<\/code>:\u00a0A payment session identifier returned by the card issuer.<\/p>\n<\/li>\n<li>\n<p><code>additionalData<\/code> including\u00a0<code>mpiImplementationType<\/code>: The merchant plug in implementation type. The value is prefixed with the\u00a0<code>mpiImplementationType<\/code> in the format:\u00a0<em><mpiImplementationType value>.<key>.\u00a0<\/em>For example, in the example above the\u00a0mpiImplementationType is\u00a0<strong>ACustom3DType<\/strong> and\u00a0all additionalData key-value pairs required to redirect the shopper to the issuer include this prefix.<\/p>\n<\/li>\n<\/ul>\n<div class=\"sc-notice note\"><div>\n<p>Store the\u00a0<code>md<\/code>\u00a0value from the response in, for example, a database, or the cookie of the shopper. You will submit this value in the\u00a0<code>authorise3d<\/code>\u00a0request after the shopper authenticates and returns to the webshop to complete the payment.<\/p>\n<\/div><\/div>\n<h2 id=\"step-2-redirect-the-shopper\">Step 2: Redirect the shopper<\/h2>\n<p>If the response to authorisation returns a <code>resultCode<\/code> with the value\u00a0<strong>RedirectShopper<\/strong> returned in the payment response:<\/p>\n<ol>\n<li>Submit all key-value pairs that are prefixed with the <code>mpiImplementationType<\/code>\u00a0using POST to the <code>issuerUrl<\/code>.<\/li>\n<li>Use a self-submitting form with a fallback in case JavaScript is disabled.<\/li>\n<\/ol>\n<div class=\"sc-notice warning\"><div>\n<p>Cut the <code>mpiImplementationType<\/code> 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.<\/p>\n<\/div><\/div>\n<p>A sample form with pseudo code\/ JSP how to construct the form:<\/p>\n<pre><code class=\"language-xml\">&lt;body onload=\"document.getElementById('3dform').submit();\"&gt;\n   &lt;form method=\"POST\" action=\"&lt;%=\"response.getIssuerUrl()\"%&gt;\" id=\"3dform\"&gt;\n      &lt;%\n         String mpiImplementation = response.getAdditionalData().get(\"mpiImplementationType\");\n\n         String keyPrefix = mpiImplementation+\".\";\n\n         for(Map.Entry&lt;String, String&gt; k : response.getAdditionalData().entrySet()) {\n\n         if(k.getKey().startsWith(keyPrefix)) {\n\n         System.out.println(\"&lt;input type=\\\"hidden\\\" name=\\\"\"\n\n         + k.getKey().substring(keyPrefix.length())\n\n         + \"\\\" value=\\\"\" + k.getValue() + \"\\\" \/&gt;\");\n\n         }\n\n         }\n\n         %&gt;\n      &lt;noscript&gt;\n         &lt;br\/&gt;\n         &lt;br\/&gt;\n         &lt;div style=\"text-align: center\"&gt;\n            &lt;h1&gt;Processing your 3-D Secure Transaction &lt;\/h1&gt;\n            &lt;p&gt;Please click continue to continue the processing\n               of your 3-D Secure transaction.\n            &lt;\/p&gt;\n            &lt;input type=\"submit\" class=\"button\" value=\"continue\"\/&gt;\n         &lt;\/div&gt;\n      &lt;\/noscript&gt;\n   &lt;\/form&gt;\n&lt;\/body&gt;<\/code><\/pre>\n<p>A sample form based on the payment response in step 1:<\/p>\n<pre><code class=\"language-xml\">&lt;body onload=\"document.getElementById('3dform').submit();\"&gt;\n   &lt;form method=\"POST\" action=\"https:\/\/issuerurl.com\/do3d\/index.php?v=abc\" id=\"3dform\"&gt;\n      &lt;input type=\"hidden\" name=\"field1\" value=\"valueForField1\" \/&gt;\n      &lt;input type=\"hidden\" name=\"field2\" value=\"valueForField2\" \/&gt;\n      &lt;input type=\"hidden\" name=\"data1\" value=\"AABBCCDD\" \/&gt;\n      &lt;input type=\"hidden\" name=\"data2\" value=\"EEFFGGHH\" \/&gt;\n      &lt;input type=\"hidden\" name=\"otherKey\" value=\"0123456789\" \/&gt;\n      &lt;noscript&gt;\n         &lt;br\/&gt;\n         &lt;br\/&gt;\n         &lt;div style=\"text-align: center\"&gt;\n            &lt;h1&gt;Processing your 3-D Secure Transaction &lt;\/h1&gt;\n            &lt;p&gt;Please click continue to continue the processing\n               of your 3-D Secure transaction.\n            &lt;\/p&gt;\n            &lt;input type=\"submit\" class=\"button\" value=\"continue\"\/&gt;\n         &lt;\/div&gt;\n      &lt;\/noscript&gt;\n   &lt;\/form&gt;\n&lt;\/body&gt;<\/code><\/pre>\n<h2 id=\"step-3-complete-the-payment\">Step 3: Complete the payment<\/h2>\n<p>After the shopper authenticates at the issuer, they will be returned to your site through a POST request to the <code>returnUrl<\/code>\u00a0sent in the initial\u00a0<code>\/authorise<\/code> request.<\/p>\n<ol>\n<li>Make an\u00a0<code>\/authorise3d<\/code>\u00a0request.<\/li>\n<li>Ensure you include the following fields:<\/li>\n<\/ol>\n<ul>\n<li>\n<ul>\n<li>\n<p><code>merchantAccount<\/code>: The merchant account to process this payment with. This should be the same as the one used in\u00a0in the initial\u00a0<code>\/authorise<\/code>\u00a0request.<\/p>\n<p><code>shopperIP<\/code>: IP address of the shopper.<\/p>\n<\/li>\n<li>\n<p><code>browserInfo.userAgent<\/code>\u00a0and\u00a0<code>browserInfo.acceptHeader<\/code>:\u00a0The user agent and accept header value of the shopper's browser.\u00a0<\/p>\n<\/li>\n<li>\n<p><code>additionalData<\/code>\u00a0including\u00a0<code>mpiImplementationType<\/code>: The merchant plug in implementation type. The value is prefixed with the\u00a0<code>mpiImplementationType<\/code>\u00a0in the format:\u00a0<em><mpiImplementationType value>.<key>.\u00a0<\/em>For example, in the example above the\u00a0mpiImplementationType is\u00a0<strong>ACustom3DType\u00a0<\/strong>and\u00a0all additionalData key-value pairs required to redirect the shopper to the issuer include this prefix.<\/p>\n<\/li>\n<li>\n<p><code>md<\/code>:\u00a0The value of the md parameter received in the response on the initial authorise request.<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p>Request:<\/p>\n<pre><code class=\"language-xml\">&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n   &lt;soap:Body&gt;\n      &lt;ns1:authorise3d xmlns:ns1=\"http:\/\/payment.services.adyen.com\"&gt;\n         &lt;ns1:paymentRequest3d&gt;\n            &lt;browserInfo xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;acceptHeader xmlns=\"http:\/\/common.services.adyen.com\"&gt;text\/xml,application\/xml,application\/xhtml+xml,text\/html;q=0.9,text\/plain;q=0.8,\nimage\/png,*\/*;q=0.5&lt;\/acceptHeader&gt;\n               &lt;userAgent xmlns=\"http:\/\/common.services.adyen.com\"&gt;Mozilla\/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko\/20070725\nFirefox\/2.0.0.6&lt;\/userAgent&gt;\n            &lt;\/browserInfo&gt;\n            &lt;md xmlns=\"http:\/\/payment.services.adyen.com\"&gt;bhh.....Q7lYlQ==&lt;\/md&gt;\n            &lt;merchantAccount xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YourMerchant&lt;\/merchantAccount&gt;\n            &lt;shopperIP xmlns=\"http:\/\/payment.services.adyen.com\"&gt;8.8.8.8&lt;\/shopperIP&gt;\n            &lt;additionalData xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.responseKey1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;abcdefgh01&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.responseKey2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;ijklmnop02&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.d1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;DA......TA1&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.d2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;DA......TA2&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;mpiImplementationType&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;ACustom3DType&lt;\/value&gt;\n               &lt;\/entry&gt;\n            &lt;\/additionalData&gt;\n         &lt;\/ns1:paymentRequest3d&gt;\n      &lt;\/ns1:authorise3d&gt;\n   &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;<\/code><\/pre>\n<p>Response:<\/p>\n<pre><code class=\"language-xml\">&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n  &lt;soap:Body&gt;\n    &lt;ns1:authorise3dResponse&gt;\n      &lt;ns1:paymentResult&gt;\n        &lt;ns1:additionalData&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;cvcResult&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;0 Unknown&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;authCode&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;d5ced7026b48537059eda1b190e8e62e4e50ccddfc8cc9d5c9e5813e64630a35&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;avsResult&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;0 Unknown&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;refusalReasonRaw&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;E000 : No_Error&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;acquirerCode&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;AcquirerCodeImplementation&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n        &lt;\/ns1:additionalData&gt;\n        &lt;ns1:pspReference&gt;9915398554833354&lt;\/ns1:pspReference&gt;\n        &lt;ns1:resultCode&gt;Authorised&lt;\/ns1:resultCode&gt;\n        &lt;ns1:authCode&gt;d5ced7026b48537059eda1b190e8e62e4e50ccddfc8cc9d5c9e5813e64630a35&lt;\/ns1:authCode&gt;\n      &lt;\/ns1:paymentResult&gt;\n    &lt;\/ns1:authorise3dResponse&gt;\n  &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;<\/code><\/pre>","url":"https:\/\/docs.adyen.com\/pt\/online-payments\/classic-integrations\/classic-api-integration\/3d-secure-authentication\/3d-secure-1\/custom-3d-secure-implementation\/custom-3d-secure-using-a-hosted-mpi","articleFields":{"id":"42838159","type":"page","_expandable":{"operations":""},"status":"current","last_edit_on":"01-05-2020 11:34","sitemap":{"priority":0.3},"parameters":{"anchor_new":"<a href=\/online-payments\/3d-secure\/other-3ds-flows\/authorize-mpidata>authorisation-only flow on Checkout API<\/a>","parent_page":"Classic API (<code>\/authorise<\/code>)","new_desc":"integrating using our Checkout APIs"}},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/online-payments\/classic-integrations\/classic-api-integration\/3d-secure-authentication\/3d-secure-1\/custom-3d-secure-implementation\/custom-3d-secure-using-a-hosted-mpi","title":"Custom 3D Secure using a hosted MPI","content":"\nAdyen is no longer developing the Classic API integration\nThis page is for the Classic API (\/authorise) integration, which we no longer accept new integrations with. \nWe strongly recommend migrating to the newer authorisation-only flow on Checkout API integration. To use this newer integration, you must also migrate to the Checkout API.\n\nStep 1: Authorise with the return URL\nSubmit API payments as a SOAP request using same URL, WSDL, username and password as normal API payments.\n\nMake an\u00a0\/authorise\u00a0request.\u00a0\nFor custom 3D secure integrations specifically, ensure you pass the following fields:\n\n\n\n\n\nreturnUrl: The URL the shopper will be redirected back to after they complete the payment. This URL can have a maximum of 1024 characters.\n\nDo 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.\n\n\n\nshopperIP: IP address of the shopper.\n\n\nbrowserInfo.userAgent\u00a0and\u00a0browserInfo.acceptHeader:\u00a0The user agent and accept header value of the shopper's browser.\u00a0\n\n\n\n\n\nThese requests and responses are only examples, use a SOAP toolkit to generate actual SOAP requests.\n\nRequest:\n&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n   &lt;soap:Body&gt;\n      &lt;ns1:authorise xmlns:ns1=\"http:\/\/payment.services.adyen.com\"&gt;\n         &lt;ns1:paymentRequest&gt;\n            &lt;amount xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;currency xmlns=\"http:\/\/common.services.adyen.com\"&gt;EUR&lt;\/currency&gt;\n               &lt;value xmlns=\"http:\/\/common.services.adyen.com\"&gt;1000&lt;\/value&gt;\n            &lt;\/amount&gt;\n            &lt;browserInfo xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;acceptHeader xmlns=\"http:\/\/common.services.adyen.com\"&gt;text\/xml,application\/xml,application\/xhtml+xml,text\/html;q=0.9,text\/plain;q=0.8,\nimage\/png,*\/*;q=0.5&lt;\/acceptHeader&gt;\n               &lt;userAgent xmlns=\"http:\/\/common.services.adyen.com\"&gt;Mozilla\/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko\/20070725\nFirefox\/2.0.0.6&lt;\/userAgent&gt;\n            &lt;\/browserInfo&gt;\n            &lt;card xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;cvc&gt;737&lt;\/cvc&gt;\n               &lt;expiryMonth&gt;12&lt;\/expiryMonth&gt;\n               &lt;expiryYear&gt;2012&lt;\/expiryYear&gt;\n               &lt;holderName&gt;T. Est&lt;\/holderName&gt;\n               &lt;number&gt;4111111111111111&lt;\/number&gt;\n            &lt;\/card&gt;\n            &lt;merchantAccount xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YourMerchant&lt;\/merchantAccount&gt;\n            &lt;reference xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YourOrderReference&lt;\/reference&gt;\n            &lt;shopperIP xmlns=\"http:\/\/payment.services.adyen.com\"&gt;61.294.12.12&lt;\/shopperIP&gt;\n            &lt;shopperReference xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j&lt;\/shopperReference&gt;\n            &lt;shopperEmail xmlns=\"http:\/\/payment.services.adyen.com\"&gt;s.hopper@test.com&lt;\/shopperEmail&gt;\n            &lt;additionalData xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;returnUrl&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;http:\/\/www.yourwebsite.com\/handle3dresult\/YourOrderReference\/&lt;\/value&gt;\n               &lt;\/entry&gt;\n            &lt;\/additionalData&gt;\n         &lt;\/ns1:paymentRequest&gt;\n      &lt;\/ns1:authorise&gt;\n   &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;\nResponse:\n&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n   &lt;soap:Body&gt;\n      &lt;ns1:authoriseResponse xmlns:ns1=\"http:\/\/payment.services.adyen.com\"&gt;\n         &lt;ns1:paymentResult&gt;\n            &lt;additionalData xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.field1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;valueForField1&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.field2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;valueForField2&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.data1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;AABBCCDD&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.data2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;EEFFGGHH&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.otherKey&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;0123456789&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;mpiImplementationType&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;ACustom3DType&lt;\/value&gt;\n               &lt;\/entry&gt;\n            &lt;\/additionalData&gt;\n            &lt;authCode xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;dccAmount xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;dccSignature xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;fraudResult xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;issuerUrl xmlns=\"http:\/\/payment.services.adyen.com\"&gt;https:\/\/issuerurl.com\/do3d\/index.php?v=abc&lt;\/issuerUrl&gt;\n            &lt;md xmlns=\"http:\/\/payment.services.adyen.com\"&gt;bhh............. Q7lYlQ==&lt;\/md&gt;\n            &lt;paRequest xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;pspReference xmlns=\"http:\/\/payment.services.adyen.com\"&gt;8313547924770610&lt;\/pspReference&gt;\n            &lt;refusalReason xmlns=\"http:\/\/payment.services.adyen.com\" xsi:nil=\"true\" \/&gt;\n            &lt;resultCode xmlns=\"http:\/\/payment.services.adyen.com\"&gt;RedirectShopper&lt;\/resultCode&gt;\n         &lt;\/ns1:paymentResult&gt;\n      &lt;\/ns1:authoriseResponse&gt;\n   &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;\nThe response will include the following parameters:\n\n\nresultCode\u00a0If the transaction is refused, for example by Risk, the resultCode will be Refused, and the response should be handled as a normal payment response.\n\n\nissuerUrl: The URL to direct the shopper to.\n\n\npspReference: The reference for the payment request.\n\n\nmd:\u00a0A payment session identifier returned by the card issuer.\n\n\nadditionalData including\u00a0mpiImplementationType: The merchant plug in implementation type. The value is prefixed with the\u00a0mpiImplementationType in the format:\u00a0..\u00a0For example, in the example above the\u00a0mpiImplementationType is\u00a0ACustom3DType and\u00a0all additionalData key-value pairs required to redirect the shopper to the issuer include this prefix.\n\n\n\nStore the\u00a0md\u00a0value from the response in, for example, a database, or the cookie of the shopper. You will submit this value in the\u00a0authorise3d\u00a0request after the shopper authenticates and returns to the webshop to complete the payment.\n\nStep 2: Redirect the shopper\nIf the response to authorisation returns a resultCode with the value\u00a0RedirectShopper returned in the payment response:\n\nSubmit all key-value pairs that are prefixed with the mpiImplementationType\u00a0using POST to the issuerUrl.\nUse a self-submitting form with a fallback in case JavaScript is disabled.\n\n\nCut 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.\n\nA sample form with pseudo code\/ JSP how to construct the form:\n&lt;body onload=\"document.getElementById('3dform').submit();\"&gt;\n   &lt;form method=\"POST\" action=\"&lt;%=\"response.getIssuerUrl()\"%&gt;\" id=\"3dform\"&gt;\n      &lt;%\n         String mpiImplementation = response.getAdditionalData().get(\"mpiImplementationType\");\n\n         String keyPrefix = mpiImplementation+\".\";\n\n         for(Map.Entry&lt;String, String&gt; k : response.getAdditionalData().entrySet()) {\n\n         if(k.getKey().startsWith(keyPrefix)) {\n\n         System.out.println(\"&lt;input type=\\\"hidden\\\" name=\\\"\"\n\n         + k.getKey().substring(keyPrefix.length())\n\n         + \"\\\" value=\\\"\" + k.getValue() + \"\\\" \/&gt;\");\n\n         }\n\n         }\n\n         %&gt;\n      &lt;noscript&gt;\n         &lt;br\/&gt;\n         &lt;br\/&gt;\n         &lt;div style=\"text-align: center\"&gt;\n            &lt;h1&gt;Processing your 3-D Secure Transaction &lt;\/h1&gt;\n            &lt;p&gt;Please click continue to continue the processing\n               of your 3-D Secure transaction.\n            &lt;\/p&gt;\n            &lt;input type=\"submit\" class=\"button\" value=\"continue\"\/&gt;\n         &lt;\/div&gt;\n      &lt;\/noscript&gt;\n   &lt;\/form&gt;\n&lt;\/body&gt;\nA sample form based on the payment response in step 1:\n&lt;body onload=\"document.getElementById('3dform').submit();\"&gt;\n   &lt;form method=\"POST\" action=\"https:\/\/issuerurl.com\/do3d\/index.php?v=abc\" id=\"3dform\"&gt;\n      &lt;input type=\"hidden\" name=\"field1\" value=\"valueForField1\" \/&gt;\n      &lt;input type=\"hidden\" name=\"field2\" value=\"valueForField2\" \/&gt;\n      &lt;input type=\"hidden\" name=\"data1\" value=\"AABBCCDD\" \/&gt;\n      &lt;input type=\"hidden\" name=\"data2\" value=\"EEFFGGHH\" \/&gt;\n      &lt;input type=\"hidden\" name=\"otherKey\" value=\"0123456789\" \/&gt;\n      &lt;noscript&gt;\n         &lt;br\/&gt;\n         &lt;br\/&gt;\n         &lt;div style=\"text-align: center\"&gt;\n            &lt;h1&gt;Processing your 3-D Secure Transaction &lt;\/h1&gt;\n            &lt;p&gt;Please click continue to continue the processing\n               of your 3-D Secure transaction.\n            &lt;\/p&gt;\n            &lt;input type=\"submit\" class=\"button\" value=\"continue\"\/&gt;\n         &lt;\/div&gt;\n      &lt;\/noscript&gt;\n   &lt;\/form&gt;\n&lt;\/body&gt;\nStep 3: Complete the payment\nAfter the shopper authenticates at the issuer, they will be returned to your site through a POST request to the returnUrl\u00a0sent in the initial\u00a0\/authorise request.\n\nMake an\u00a0\/authorise3d\u00a0request.\nEnsure you include the following fields:\n\n\n\n\n\nmerchantAccount: The merchant account to process this payment with. This should be the same as the one used in\u00a0in the initial\u00a0\/authorise\u00a0request.\nshopperIP: IP address of the shopper.\n\n\nbrowserInfo.userAgent\u00a0and\u00a0browserInfo.acceptHeader:\u00a0The user agent and accept header value of the shopper's browser.\u00a0\n\n\nadditionalData\u00a0including\u00a0mpiImplementationType: The merchant plug in implementation type. The value is prefixed with the\u00a0mpiImplementationType\u00a0in the format:\u00a0..\u00a0For example, in the example above the\u00a0mpiImplementationType is\u00a0ACustom3DType\u00a0and\u00a0all additionalData key-value pairs required to redirect the shopper to the issuer include this prefix.\n\n\nmd:\u00a0The value of the md parameter received in the response on the initial authorise request.\n\n\n\n\nRequest:\n&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n   &lt;soap:Body&gt;\n      &lt;ns1:authorise3d xmlns:ns1=\"http:\/\/payment.services.adyen.com\"&gt;\n         &lt;ns1:paymentRequest3d&gt;\n            &lt;browserInfo xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;acceptHeader xmlns=\"http:\/\/common.services.adyen.com\"&gt;text\/xml,application\/xml,application\/xhtml+xml,text\/html;q=0.9,text\/plain;q=0.8,\nimage\/png,*\/*;q=0.5&lt;\/acceptHeader&gt;\n               &lt;userAgent xmlns=\"http:\/\/common.services.adyen.com\"&gt;Mozilla\/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko\/20070725\nFirefox\/2.0.0.6&lt;\/userAgent&gt;\n            &lt;\/browserInfo&gt;\n            &lt;md xmlns=\"http:\/\/payment.services.adyen.com\"&gt;bhh.....Q7lYlQ==&lt;\/md&gt;\n            &lt;merchantAccount xmlns=\"http:\/\/payment.services.adyen.com\"&gt;YourMerchant&lt;\/merchantAccount&gt;\n            &lt;shopperIP xmlns=\"http:\/\/payment.services.adyen.com\"&gt;8.8.8.8&lt;\/shopperIP&gt;\n            &lt;additionalData xmlns=\"http:\/\/payment.services.adyen.com\"&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.responseKey1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;abcdefgh01&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.responseKey2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;ijklmnop02&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.d1&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;DA......TA1&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;ACustom3DType.d2&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;DA......TA2&lt;\/value&gt;\n               &lt;\/entry&gt;\n               &lt;entry&gt;\n                  &lt;key xsi:type=\"xsd:string\"&gt;mpiImplementationType&lt;\/key&gt;\n                  &lt;value xsi:type=\"xsd:string\"&gt;ACustom3DType&lt;\/value&gt;\n               &lt;\/entry&gt;\n            &lt;\/additionalData&gt;\n         &lt;\/ns1:paymentRequest3d&gt;\n      &lt;\/ns1:authorise3d&gt;\n   &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;\nResponse:\n&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;\n&lt;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\"&gt;\n  &lt;soap:Body&gt;\n    &lt;ns1:authorise3dResponse&gt;\n      &lt;ns1:paymentResult&gt;\n        &lt;ns1:additionalData&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;cvcResult&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;0 Unknown&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;authCode&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;d5ced7026b48537059eda1b190e8e62e4e50ccddfc8cc9d5c9e5813e64630a35&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;avsResult&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;0 Unknown&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;refusalReasonRaw&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;E000 : No_Error&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n          &lt;ns1:entry&gt;\n            &lt;ns1:key xsi:type=\"xsd:string\"&gt;acquirerCode&lt;\/ns1:key&gt;\n            &lt;ns1:value xsi:type=\"xsd:string\"&gt;AcquirerCodeImplementation&lt;\/ns1:value&gt;\n          &lt;\/ns1:entry&gt;\n        &lt;\/ns1:additionalData&gt;\n        &lt;ns1:pspReference&gt;9915398554833354&lt;\/ns1:pspReference&gt;\n        &lt;ns1:resultCode&gt;Authorised&lt;\/ns1:resultCode&gt;\n        &lt;ns1:authCode&gt;d5ced7026b48537059eda1b190e8e62e4e50ccddfc8cc9d5c9e5813e64630a35&lt;\/ns1:authCode&gt;\n      &lt;\/ns1:paymentResult&gt;\n    &lt;\/ns1:authorise3dResponse&gt;\n  &lt;\/soap:Body&gt;\n&lt;\/soap:Envelope&gt;","type":"page","locale":"pt","boost":13,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Classic integrations for Ecommerce","lvl3":"Classic API integration","lvl4":"3D Secure authentication","lvl5":"3D Secure 1 and 2 redirect authentication","lvl6":"Custom 3D Secure implementation","lvl7":"Custom 3D Secure using a hosted MPI"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/online-payments","lvl2":"https:\/\/docs.adyen.com\/pt\/online-payments\/classic-integrations","lvl3":"https:\/\/docs.adyen.com\/pt\/online-payments\/classic-integrations\/classic-api-integration","lvl4":"https:\/\/docs.adyen.com\/pt\/online-payments\/classic-integrations\/classic-api-integration\/3d-secure-authentication","lvl5":"https:\/\/docs.adyen.com\/pt\/online-payments\/classic-integrations\/classic-api-integration\/3d-secure-authentication\/3d-secure-1","lvl6":"https:\/\/docs.adyen.com\/pt\/online-payments\/classic-integrations\/classic-api-integration\/3d-secure-authentication\/3d-secure-1\/custom-3d-secure-implementation","lvl7":"\/pt\/online-payments\/classic-integrations\/classic-api-integration\/3d-secure-authentication\/3d-secure-1\/custom-3d-secure-implementation\/custom-3d-secure-using-a-hosted-mpi"},"levels":8,"category":"Online Payments","category_color":"green","tags":["Custom","Secure","using","hosted"]}}