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 shopper journey for a 3D Secure is different to a regular card payment. When 3D Secure authentication is required, the shopper additionally needs to verify the payment with their bank before it can be completed. 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 No 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 SDKs you'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, and carries a per transaction fee. 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.

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

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

Step 1: Collect shopper details

When a shopper chooses to pay by card: 

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

    Card details Example
    The card number "4212345678901237"
    The card expiry month "10"
    The card expiry year "20"
    The security code (CVV / CVC) "737"
    Optional: The card holder's name "J Smith"

    Unless you are PCI Level 1 or 2 certified, you'll need to encrypt these details using our Secured Fields JavaScript Library.

Step 2: Make a payment

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

    • encryptedExpiryYear: The encrypted card expiry year.
    • encryptedSecurityCode: The encrypted card verification code.
    • holderName: The card holder'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 can provide a smoother authentication flow for the shopper.
    {
       "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

    • redirect object 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 you received.

    curl --user 'X-API-Key' 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

Once 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, and include: 
    • 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, which 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 via your website or app. Check our result codes documentation for information on what these mean, and what 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

You'll know that a payment has been successful when you 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, you will need to collect and submit an 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, so 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 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 on Dynamic 3D Secure, see our Dynamic 3D Secure documentation.

Testing 3D Secure payments

Before going live, you can 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

For 3D Secure verification, 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