Cards with 3D Secure

Learn how to accept 3D Secure authenticated card payments.


3D Secure is an additional layer of credit card authentication. When used for a personal card payment, the issuing bank becomes liable for fraudulent chargebacks.

The payment flow for a 3D Secure is different to a regular card payment. To complete a card payment with 3D Secure authentication, the shopper must verify the payment with their bank. This usually involves entering a unique password or SMS code on their bank's website.

3D Secure authentication is supported by the following card schemes:

  • American Express
  • Cartes Bancaires
  • China UnionPay (only with our API integration)
  • Diners / Discover
  • JCB
  • Maestro
  • Mastercard
  • Visa

Not all cards issued by these schemes support 3D Secure.

Payment Type
Payment flow
Recurring
Refunds
Partial Refunds
Captures
Partial Captures
Chargebacks
Credit card Redirect Yes Yes Yes Yes Yes Yes, for non-fraud

You can accept 3D Secure authenticated card payments with:

Integrate with Checkout SDKs

To use 3D Secure with our Checkout SDKsyou'll need to enable Dynamic 3D Secure, and set up rules to determine which card payments will use 3D Secure.

Dynamic 3D Secure also requires additional configuration by Adyen. To enable this feature, contact our Support Team team.

Integrate with API

In this section we show you the API integration steps for cards with 3D Secure.

Before you begin this section, make sure you read and understand our API Integration guide.

Step 1: Collect shopper details

 To collect the shopper's details, you can either:

Collect with Card Component 

 To add the Card Component to your payments form:

  1. Create a DOM element, placing it where you want the card form to be rendered:

    <div id="card"></div>
  2. Create an instance of the Card Component, and mount it:

    const card = checkout.create("card", {
        onChange: handleOnChange
    }).mount("#card");

    Make sure you add a Components common configuration.

  3. Create a function to listen to and handle the onChange event triggered by the Component:

    function handleOnChange(state, component) {
        state.isValid // true or false.
        state.data
        /* {type: "scheme",
            encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
            encryptedExpiryMonth: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
            encryptedExpiryYear: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
            encryptedSecurityCode: "adyenjs_0_1_18$MT6ppy0FAMVMLH..."}
        */
    }
  4. When state.isValid is true, collect the encrypted values passed in the state.data. You'll use these to make the payment.

Collect with your own payments form 

Before you collect card data in your payments form, make sure you read and understand our Build your own payment form guide.

 If you're using your own payments form, when a shopper chooses to pay by card:

  • Collect the following card details from the shopper in your payment form using Secured Fields:

    If you are PCI Level 1 or 2 certified you can pass raw card data instead.

    Card details Example input
    The card number "4111111111111111"
    The card expiry month "03"
    The card expiry year "30"
    The security code (CVV / CVC) "737"
    Optional: The card holder's name. Do not encrypt this. "J Smith"

    You'll use the encrypted card values passed by the Secured Fields to make the payment.

To use SecurePlus authentication for China UnionPay, some additional configuration is required.

Step 2: Make a payment

  • Make a /payments API call, providing:
    • reference: Your unique reference for this payment.
    • amount.
    • paymentMethod.type: scheme.
    • encryptedCardNumber: Encrypted card number (without separators).
    • encryptedExpiryMonth: Encrypted card expiry month.

    • encryptedExpiryYear: Encrypted card expiry year.
    • encryptedSecurityCode: Encrypted card verification code.
    • holderName: Cardholder's name. This is optional.
    • additionalData.executeThreeD: true. Set this to false to skip 3D Secure authentication.
    • returnUrl: The URL the shopper will be redirected back to after completing 3D Secure authentication.
    • browserInfo. The shopper's browserinfo. Providing this is optional, but provides a smoother authentication flow for the shopper.

    Here we use encrypted card details, generated by our Secured Fields JavaScript Library. If you are PCI Level 1 or 2 certified, you can provide raw card data instead.

    {
       "merchantAccount":"YourMerchantAccount",
       "reference":"3d secure test",
       "amount":{
          "currency":"EUR",
          "value":1000
       },
       "paymentMethod":{
          "type":"scheme",
          "encryptedCardNumber":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
          "encryptedExpiryMonth":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
          "encryptedExpiryYear":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
          "encryptedSecurityCode":"adyenjs_0_1_18$MT6ppy0FAMVMLH..."
       },
       "additionalData":{
          "executeThreeD":"true"
       },
       "returnUrl":"https://your-company.com/checkout/",
       "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"
       }
    }

    If the shopper's card supports 3D Secure, you'll receive a response containing:

    • resultCode of RedirectShopper.

    • paymentData: Payload needed to verify the payment

    • redirectObject containing information needed to redirect the shopper: 

      • data.PaReq: Payload needed when redirecting the shopper. 

      • data.TermUrl: The returnUrl you provided in the request.

      • data.MD: Payload needed to verify the payment

      • url: Used to redirect the shopper to complete 3D Secure verification.

    {
       "resultCode":"RedirectShopper",
       "details":[
          {
             "key":"MD",
             "type":"text"
          },
          {
             "key":"PaRes",
             "type":"text"
          }
       ],
       "paymentData":"Ab02b4c0!BQABAgBKNFnhRjSn4jZPsP7nywoY...",
       "redirect":{
          "data":{
             "PaReq":"eNpVUttygjAQ/RXbDyAJl4LMmg6VztQH1LH63GHCjtApAQNU9O...",
             "TermUrl":"https://your-company.com/checkout/",
             "MD":"djIhMFQxMHpFRHlyY3BOSHJ1UUNmZnk1Zz09IZ3a9YOyDsr30Ni+jrj0M3pyy..."
          },
          "method":"POST",
          "url":"https://test.adyen.com/hpp/3d/validate.shtml"
       }
    }

    If a card does not support 3D Secure you'll receive the same response as a regular credit card payment.

Step 3: Redirect shopper

Redirect the shopper to the card issuer to complete 3D Secure verification:

  • Use the url in the /payments response to make an HTTP POST. Append this with the fields you received in the redirect.data object.

    curl https://test.adyen.com/hpp/3d/validate.shtml \
    --data-urlencode 'PaReq=eNpVUttygjAQ/RXbDyAJl4LMmg6VztQH1LH63GHCjtApAQNU9O...' \
    --data-urlencode 'TermUrl=https://your-company.com/...' \
    --data-urlencode 'MD=djIhMFQxMHpFRHlyY3BOSHJ1UUNmZnk1Zz09IZ3a9YOyDsr30Ni+jrj0M3pyy...'

Step 4: Complete payment

After the shopper has successfully completed 3D Secure verification, the card issuer will redirect them back to your website via an HTTP POST. This will be appended with MD and PaRes variables. To verify the result of the payment:

  • Make a call to /payments/details, including: 
    • paymentData: Value you received in the /payments response.
    • MD: Value you received when the shopper was redirected back to your website.
    • PaRes: Value you received when the shopper was redirected back to your website.
    {
       "paymentData":"Ab02b4c0!BQABAgBKNFnhRjSn4jZPsP7nywoY...",
       "details":{
          "MD":"djIhMFQxMHpFRHlyY3BOSHJ1UUNmZnk1Zz09IZ3a9YOyDsr30Ni+jrj0M3pyy...",
          "PaRes":"eNpVUttygjAQ/RXrB5CLoJFZM5PKQ31QacXnDhN2lGkBDVDl75uAlzZP5+zZ3eyeB..."
       }
    }

    The response will contain a resultCode and a pspReference. The pspReference is our unique identifier for the transaction.

Step 5: Present payment result

  • Use the resultCode you received from the /payments/details endpoint to present the shopper with the result of the payment in your website or app. Check our result codes documentation for information on what these mean and the actions you should take.

3D Secure notifications

Accepting notifications is not required for 3D Secure authenticated card payments, but we recommend that you set them up. Each notification has a:

  • pspReference: identifies which payment is being referred to.
  • eventCode: indicates the status of the payment.

If you haven't already set up notifications, refer to our notifications documentation for instructions.

Successful payments

When a payment is successful you'll receive a notification for the transaction that has: 

  • eventCodeAUTHORISATION. 
  • successtrue.

SecurePlus authentication

SecurePlus is the 3D Secure authentication layer used by China UnionPay. Instead of redirecting the shopper to verify a payment, collect and submit the SMS verification code sent to them by China UnionPay.

SecurePlus is not supported by our Checkout SDKs at this time.

To use SecurePlus authentication with our API integration:

  1. When you collect the shopper's payment details, additionally collect their telephone number.
  2. When you make the payment, additionally include: 

    • paymentMethod.telephoneNumber: The shopper's telephone number.

    {
       "merchantAccount":"YourMerchantAccount",
       "amount":{
          "currency":"CNY",
          "value":1000
       },
       "reference":"secureplus test",
       "paymentMethod":{
          "type":"scheme",
          "encryptedCardNumber":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
          "encryptedExpiryMonth":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
          "encryptedExpiryYear":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
          "encryptedSecurityCode":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
          "telephoneNumber":"+85211112222"
       },
       "additionalData":{
          "executeThreeD":"true"
       },
       "returnUrl":"https://your-company.com/checkout/",
       "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"
       }
    }

    If SecurePlus authentication is supported, you'll receive a resultCode of Pending.

    {
      "resultCode":"Pending",
      "details":[
        {
          "key":"cupsecureplus.smscode",
          "type":"text"
        },
        {
          "key":"MD",
          "type":"text"
        }
      ],
      "paymentData":"Ab02b4c0!BQABAgBKNFnhRjSn4jZPsP7nywoY...",
      "redirect":{
        "data":{
          "MD":"djIhMFQxMHpFRHlyY3BOSHJ1UUNmZnk1Zz09IZ3a9YOyDsr30Ni+jrj0M3pyy..."
        }
      }
    }

    If the card does not support SecurePlus verification you'll receive the same response as a regular credit card payment.

  3. Present a screen in your UI to collect the SMS verification code that was sent to the shopper.
  4. When you complete the payment, additionally include:

    • cupsecureplus.smscode : The SMS verification code you collected from the shopper.

    {
      "paymentData":"Ab02b4c0!BQABAgBKNFnhRjSn4jZPsP7nywoY...",
      "details":{
        "MD":"djIhMFQxMHpFRHlyY3BOSHJ1UUNmZnk1Zz09IZ3a9YOyDsr30Ni+jrj0M3pyy...",
        "cupsecureplus":{
          "smscode":"123456"
        }
      }
    }
  5. Present the payment result to your shopper.

Dynamic 3D Secure

While 3D Secure reduces the risk of fraudulent payments, many shoppers are still unfamiliar with the authentication process, and do not complete payment verification. In addition, client-side technical errors can occur when the shopper is being redirected, further lowering your conversion rate.

To counter these issues we developed Adyen Dynamic 3D Secure. This lets you use rules to determine which payments are routed though 3D Secure authentication, and which are processed without.

Dynamic 3D Secure requires additional configuration by Adyen, and carries a per transaction fee. To enable this feature, contact our Support Team team.

For more information, see our Dynamic 3D Secure documentation.

Testing 3D Secure payments

Before going live, use the following card numbers and credentials to test your integration.

We recommend testing each Card Type.

Card Type Card Number Country Expiry Month Expiry Year Security Code (CVC/CVV)
American Express 3451 7792 5488 348 International 10 2020 7373
International 6731 0123 4567 8906 NL 10 2020 737
JCB 3569 9900 1009 5833 US 10 2020 737
Maestro 6771 8309 9999 1239 GB 10 2020 737
Maestro 6771 8300 0000 0000 006 GB 10 2020 737
Mastercard 5212 3456 7890 1234 JP 10 2020 737
Visa 4212 3456 7890 1237 CA 10 2020 737

When prompted for 3D Secure authentication, use the following credentials:

  • Username: user
  • Password: password

You can check the status of 3D Secure test payments in your Customer Area > Transactions > Payments.

See also