{"title":"Redirect 3DS Drop-in integration","category":"default","creationDate":1693431120,"content":"
\n

\"\"  Postman collection<\/a><\/p>

Implementation examples<\/strong>
\"\"  Node.js<\/a><\/p>\n  \n  \n\n <\/div><\/div>\n\n

Our Web Drop-in<\/a> renders the available cards in your payment form, and securely collects any sensitive card information, so it doesn't touch your server. Drop-in also redirects the shopper to perform the 3D Secure 2 authentication.<\/p>\n

\n

Follow the instructions on this page if your integration uses the \/payments<\/a> or \/payments\/details<\/a> endpoint, and Checkout API 49 or later.
\n
If your integration uses only the \/sessions<\/a> endpoint, you do not need additional configuration for 3D Secure. If you are using Checkout API 46 or earlier, follow instructions in the 3D Secure 2 integration guide for v46 or earlier<\/a>.<\/p>\n<\/div><\/div>\n

When adding card payments with redirect 3D Secure authentication to your integration, you additionally need to:<\/p>\n

    \n
  1. Configure Drop-in<\/a> to collect the card holder name.<\/li>\n
  2. Provide the required 3D Secure parameters<\/a> when making a payment request.<\/li>\n
  3. Handle the redirect result<\/a> after the shopper returns to your website.<\/li>\n<\/ol>\n

    Requirements<\/h2>\n

    This page explains how to add cards with redirect 3D Secure authentication to an existing Web Drop-in integration. The Web Drop-in integration works the same way for all payment methods. If you haven't done this integration yet, refer to our Drop-in integration guide<\/a>.<\/p>\n

    Before starting your integration:<\/p>\n

      \n
    1. Make sure that you have set up your back end implementation<\/a>, and added Drop-in to your payments form<\/a>.<\/li>\n
    2. Add the cards that you want to accept in your test Customer Area<\/a>.<\/li>\n
    3. If you are using 3D Secure for PSD2 compliance, read our comprehensive PSD2 SCA guide<\/a>.<\/li>\n<\/ol>\n

      Show the available cards in your payment form<\/h2>\n
      \n

      For information about the supported countries\/regions and currencies for each card, refer to Payment methods<\/a>.<\/p><\/div><\/div>\n\n

      Drop-in uses the combination of countryCode<\/a> and amount.currency<\/a> from your \/paymentMethods<\/a> request to show the available cards to your shopper.<\/p>\n

      When the shopper is entering their card details, Drop-in tries to recognize the card brand. When successful, Drop-in renders the brand icon and the corresponding input field for the card security code (CVC, CVV, or CID).<\/p>\n

      Collect additional parameters in your payment form<\/h2>\n

      For higher authentication rates, we strongly recommend that you collect the card holder name, billing address, and email address for payments with 3D Secure authentication.<\/p>\n

      Configure Drop-in<\/h3>\n

      When creating an instance of Drop-in<\/a>, you can optionally specify the following fields:<\/p>\n\n\n\n\n\n\n\n\n\n
      Field<\/th>\nDescription<\/th>\nDefault<\/th>\n<\/tr>\n<\/thead>\n
      hasHolderName<\/code><\/td>\nSet to\u00a0true<\/strong>\u00a0to show the input field for the card holder name.<\/td>\nfalse<\/strong><\/td>\n<\/tr>\n
      holderNameRequired<\/code><\/td>\nSet to\u00a0true<\/strong>\u00a0to make the card holder name a required field. To show the field, you additionally need to set hasHolderName<\/code> to true<\/strong>.<\/td>\nfalse<\/strong><\/td>\n<\/tr>\n
      enableStoreDetails<\/code><\/td>\nSet to\u00a0true<\/strong>\u00a0to show the checkbox for saving the card details for recurring payments.<\/td>\nfalse<\/strong><\/td>\n<\/tr>\n
      name<\/code><\/td>\nString that is used to display the payment method name to the shopper.<\/td>\nDepends on the shopperLocale<\/code> specified in \/paymentMethods<\/code> request.<\/td>\n<\/tr>\n
      billingAddressRequired<\/code><\/td>\n
      \n \n v 3.5.0\n <\/tag>\n<\/div>\n Set to true<\/strong> to collect the shopper's billing address.<\/td>\n
      		false<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
      const dropin = checkout\n   .create('dropin', {\n       paymentMethodsConfiguration: {\n           card: { \/\/ Sample Drop-in configuration for 3D Secure\n               hasHolderName: true,\n               holderNameRequired: true,\n               enableStoreDetails: true,\n               name: 'Credit or debit card',\n               billingAddressRequired: true\n           },\n           ...\n       }\n   })\n   .mount('#dropin');<\/code><\/pre>\n
      You can also customize your shopper's experience with optional configuration parameters<\/a> and specific events<\/a>.<\/p>\n
      Collect shopper email in your payment form<\/h3>\n
      We also recommend that you collect the shopper email in advance in your payment form. Deliver this parameter to your backend when making a payment<\/a>, because it is required by the card schemes.<\/p>\n
      Make a payment<\/h2>\n
      When the shopper selects to pay, Drop-in calls the onSubmit<\/code> event, which contains a state.data<\/code>.<\/p>\n
        \n
      1. \n
        Pass the state.data<\/code> to your server.<\/p>\n<\/li>\n
      2. \n
        When you make a payment request<\/a>, include the following additional 3D Secure 2 parameters.<\/p>\n
        \n
        See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our API reference<\/a>.<\/p>\n<\/div>\n\n\n\n\n\n\n\n\n\n\n\n\n\n
        Parameter name<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
         paymentMethod<\/a><\/td>\n\"Required\"<\/span><\/td>\nThe type and required details for a card payment method. This is the state.data.paymentMethod<\/code> object from the onSubmit<\/code> event.<\/td>\n<\/tr>\n
         paymentMethod.holderName<\/a><\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: required for Visa and JCB transactions. 
         The cardholder's name.<\/td>\n<\/tr>\n
         browserInfo<\/a><\/td>\n\"Required\"<\/span><\/td>\nThe shopper's browser information. All sub-fields of this object are required for channel<\/code>: Web<\/strong>. This is the state.data.browserInfo<\/code> object from the onSubmit<\/code> event.<\/td>\n<\/tr>\n
         channel<\/a><\/td>\n\"Required\"<\/span><\/td>\nThe platform where the transaction takes place. Set to Web<\/strong>.<\/td>\n<\/tr>\n
         origin<\/a><\/td>\n\"Required\"<\/span><\/td>\nThe origin URL of the page where you are rendering Drop-in. To get the origin, open the browser console and call window.location.origin<\/code>. 
         When this field is not set, or set incorrectly, the 3D Secure 2 action can not be handled correctly.  
         Format<\/strong>: 
        • Maximum characters: 80.<\/li>
        • Do not include subdirectories and a trailing slash.<\/li><\/ul> Example<\/strong>: if you render Drop-in on https:\/\/your-company.example.com\/checkout\/payment<\/code>, set to https:\/\/your-company.example.com<\/code>. 
          <\/td>\n<\/tr>\n
         returnUrl<\/a><\/td>\n\"Required\"<\/span><\/td>\nThe URL where the shopper is redirected back to after completing authentication, including the protocol http:\/\/<\/code> or https:\/\/<\/code>. You can also include your own additional query parameters, for example, shopper ID or order reference number.  
         Format<\/strong>: 
        • The return URL must not include \/\/<\/code> (double slash) after the top-level domain.<\/li>
        • Maximum characters: 1024. We recommend that you keep the number of characters as small as possible.<\/li><\/ul> Example<\/strong>: https:\/\/your-company.example.com\/checkout\/<\/code>.<\/td>\n<\/tr>\n
         shopperEmail<\/a><\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: required for Visa and JCB transactions. 
         The cardholder's email address. If you do not include the shopper email, you must include the shopper's phone number in your request.<\/td>\n<\/tr>\n
         shopperIP<\/a><\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: required for Visa and JCB transactions on the web. 
         The shopper's IP address.<\/td>\n<\/tr>\n
         telephoneNumber<\/a><\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: required for Visa and JCB transactions if you did not include the shopperEmail<\/code> field. 
        The shopper's phone number. To be more specific, you can use the mobilePhone<\/code>, homePhone<\/code>, and workPhone<\/code> fields in the threeDS2RequestData<\/code> object.  
         Format<\/strong>: The phone number must include a plus sign (+) and a country code (1-3 digits), followed by the number (4-15 digits). 
          Example<\/strong>: +4912345678901<\/strong> 
         If the value you provide does not follow the guidelines, we drop the value and do not submit it for authentication. <\/div><\/div><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
        \"This Required for all transactions. 
        \"This Required for particular setups, or issuers and card schemes. 
        \"This Recommended for all transactions, but not required.<\/p>\n
        \n<\/code-sample>\n<\/div>\n<\/li>\n
      3. \n
        In the response, check if there is an action<\/code> object.<\/p>\n\n
        \n    
        \n        \n        <\/tabs>\n    <\/div>\n<\/div>\n\n<\/li>\n<\/ol>\n
        Handle the redirect<\/h2>\n
        Drop-in uses dropin.handleAction(action)<\/code> to redirect the shopper to a page where we render the issuer's DOM element (the action.url<\/code> from the  \/payments<\/a> response) to perform 3D Secure authentication.<\/p>\n
        In our test environment, this is the page: https:\/\/checkoutshopper-test.adyen.com\/checkoutshopper\/identifyShopper.shtml<\/code>, and you perform the authentication using the 3D Secure test credentials:<\/p>\n