Learn how to accept 3D Secure authenticated card payments.
For 3D Secure 2 implementation, see 3D Secure 2 API integration.
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
Not all cards issued by these schemes support 3D Secure.
|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
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:
Create a DOM element, placing it where you want the card form to be rendered:
Create an instance of the Card Component, and mount it:
Create a function to listen to and handle the
onChangeevent triggered by the Component:
state.isValidis 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:
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
/paymentsAPI call, providing:
reference: Your unique reference for this payment.
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 the Card Component. If you are PCI Level 1 or 2 certified, you can provide raw card data instead.
If the shopper's card supports 3D Secure, you'll receive a response containing:
paymentData: Payload needed to verify the payment.
redirect: Object containing information needed to redirect the shopper:
data.PaReq: Payload needed when redirecting the shopper.
returnUrlyou provided in the request.
data.MD: Payload needed to verify the payment.
url: Used to redirect the shopper to complete 3D Secure verification.
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:
/paymentsresponse to make an HTTP POST. Append this with the fields you received in the
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
PaRes variables. To verify the result of the payment:
- Make a call to
paymentData: Value you received in the
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.
The response will contain a
pspReferenceis our unique identifier for the transaction.
Step 5: Present payment result
- Use the
resultCodeyou received from the
/payments/detailsendpoint 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.
When a payment is successful you'll receive a notification for the transaction that has:
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:
- When you collect the shopper's payment details, additionally collect their telephone number.
When you make the payment, additionally include:
paymentMethod.telephoneNumber: The shopper's telephone number.
If SecurePlus authentication is supported, you'll receive a
If the card does not support SecurePlus verification you'll receive the same response as a regular credit card payment.
- Present a screen in your UI to collect the SMS verification code that was sent to the shopper.
When you complete the payment, additionally include:
cupsecureplus.smscode: The SMS verification code you collected from the shopper.
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. To enable this feature, contact our Support Team team.
For more information, see our Dynamic 3D Secure documentation.
Configuring the Component
Our Card Component has several options you can configure, including properties used for Secured Fields.
When instantiating the Card Component, you can optionally specify:
details: Set an object containing the
type: schemefrom the
enableStoreDetails: Set to true to show the checkbox to save card details for the next payment.
hasHolderName: Set to true to request the name of the card holder.
holderNameRequired: Set to true to require the card holder name.
groupTypes: Defaults to
['mc','visa','amex']. Configure supported card types to facilitate brand recognition used in the Secured Fields
onBrandcallback. See list of available card types. If a shopper enters a card type not specified in the
GroupTypesconfiguration, the onBrand callback will not be invoked.
styles: Set a style object to customize the input fields. See Styling Secured Fields for a list of supported properties.
placeholders: Specify the sample values you want to appear for card detail input fields.
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.