No momento, esta página não está disponível em português
Classic-integration icon

3D Secure 1 and 2 redirect authentication

Learn how you can support both versions of 3D Secure through a redirect page with your classic API integration.

Adyen is no longer developing the Classic API integration

This page is for the Classic API (/authorise) integration, which we no longer accept new integrations with.

We strongly recommend switching to the newer 3D Secure redirect authentication on Checkout API integration.

3D Secure is a protocol provided by credit card schemes. It is an additional authentication protocol that allows you to implement another layer of security on your Card-Not-Present transactions.

During a 3D Secure transaction, the shopper is redirected to a site controlled by the issuing bank to answer additional security questions (usually a unique password or SMS verification). This reduces the chance of a fraudulent transaction occurring.

When 3D Secure is used for personal cards, the chargeback liability shifts to the issuing banks.

While this liability shift is appealing, there is a significant risk of a lower conversion rate when you use 3D Secure. This is because many shoppers are still not familiar with 3D Secure, so may not pass the verification process. Client-side technical errors may also occur when they are redirected.

Adyen has developed a robust dynamic 3D Secure system. This lets you choose which transactions are sent for 3D Secure authentication, and which are processed without. For more information, read Dynamic 3D Secure.

Managing PSD2 SCA compliance with 3D Secure

If you are implementing 3D Secure to handle PSD2 compliance, your options are to:

  1. Let Adyen handle PSD2 compliance by default.
  2. Configure rules using Dynamic 3D Secure.
  3. Submit your preference for each transaction in your API request.

In this integration guide, we talk about the steps on how you can submit 3D Secure requests for options 1 and 2.

If you want to use option 3 to send your preference for each transaction in your API request, you will need to submit additional fields. However, note that option 3 overrides our default PSD2 compliance handling logic, including checking if the transaction is out of scope, determining the most suitable exemption type to request for, and evaluating whether to send the exemption in the authentication or authorisation request.

We recommend using option 3 only if you have an extensive knowledge of PSD2 SCA regulations and the 3D Secure protocol.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

  • Get an overview of the steps needed to accept live payments.
  • Create your test account.

After you have created your test account:

  1. Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.
  2. Check if 3D Secure 1 is enabled on your account.

Enable 3D Secure

For the test environment, 3D Secure is enabled by default.

For the live environment, it is enabled by default for:

  • Bancontact / MisterCash
  • Maestro (SecureCode)
  • Mastercard (SecureCode)
  • Visa (Visa Secure)

Contact the Support Team to configure live 3D Secure transactions for:

  • American Express (SafeKey)
  • Diners / Discover (ProtectBuy)
  • JCB (J/Secure)

Step 1: Authorise the 3D Secure payment

This documentation explains how to implement 3D Secure with the classic integration. For details on our newer integration, refer to 3D Secure 2 on Checkout API instead.

The following example illustrates the /authorise call to initiate a 3D Secure payment.

  • Make a POST /authorise request, providing:

    • reference: Your unique reference for this payment.
    • amount
    • card: Object that contains the shopper's card details.

      • number: Encrypted card number.
      • expiryMonth: Encrypted card expiry month.
      • expiryYear: Encrypted card expiry year.
      • cvc: Encrypted card verification code.
      • holderName: Cardholder's name.

        You can only pass raw card data if you are fully PCI compliant. Otherwise, you should use the Client-Side Encryption library to authorise a payment.

    • browserInfo: The shopper's browser information.
    • shopperIP: The shopper's IP address.

      If you are using the redirect authentication for 3D Secure 2, we recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorisation rate. In addition to the regular parameters you provide to Adyen, send additional parameters in this list.

Response

The /authorise response contains a resultCode of either:

  • Authorised, or any other resultCodes that you can get for a normal /authorise request. This can happen in case of a frictionless flow (where a liability shift still occurs), or if the card is not enrolled in the 3D Secure program.

  • RedirectShopper: Indicates that you need to redirect the shopper to the card issuer for 3D Secure authentication. The response also contains:  

    • paRequest
    • md
    • issuerUrl: URL to where you should redirect the shopper to complete the 3D Secure authentication.
 {
    "additionalData": {
        "paymentMethod": "mc",
        "paymentMethodVariant": "maestro"
    },
    "pspReference": "8535033222809597",
    "resultCode": "RedirectShopper",
    "issuerUrl": "https://issuer-url-here.com",
    "md": "NnheOml4nhgrnx...pP6oBb3KQqKXiYGL3X8=",
    "paRequest": "eNpVUttygjAQ/R...jI+ts3+f4Afk4a3Y"
}

For more information about these fields, refer to PaymentResult.

Step 2: Redirect to the card issuer

If you receive a resultCode RedirectShopper in the /authorise response, you need to redirect the shopper to the card issuer for 3D Secure verification.

You can use an HTML form that you submit with an HTTP POST method call to the URL endpoint specified in issuerUrl. The form should be self-submitting, with a fallback option in case the shopper disabled JavaScript in their web browser. We recommend that you use an HTTPS connection.

In the form, include the following input elements:

  • PaReq – corresponds to paRequest and holds the 3D Secure request data for the issuer.
  • MD – corresponds to md. A payment session identifier returned by the card issuer. Note that it must be uppercase in the POST message to the issuer.
  • TermUrl – corresponds to termUrl. After completing 3D Secure verification on the card issuer site, the shopper is redirected back to the merchant site. This URL value specifies which merchant site page the shopper goes back to. The maximum size is 1024 characters.

The following sample shows an example HTML form:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>Adyen - Create 3D Secure Payment</title>
    </head>
    <body onload="document.getElementById('3dform').submit();">
        <form method="POST" action="${IssuerUrl}" id="3dform">
            <input type="hidden" name="PaReq" value="${PaReq}" />
            <input type="hidden" name="MD" value="${MD}" />
            <input type="hidden" name="TermUrl" value="${TermUrl}" />
            <noscript>
                <br>
                <br>
                <div style="text-align: center">
                    <h1>Processing your 3D Secure Transaction</h1>
                    <p>Please click continue to continue the processing of your 3D Secure transaction.</p>
                    <input type="submit" class="button" value="continue"/>
                </div>
            </noscript>
        </form>
    </body>
</html>

Step 3: Return to the merchant site

After a successful 3D Secure verification, the card issuer redirects the shopper to your website. In this case, you will receive an HTTP POST or GET call to the URL that you specified in TermUrl. We recommend that you use an HTTPS connection.

The HTTP POST or GET call from the card issuer to your URL includes the following parameters:

  • MD – A payment session identifier returned by the card issuer.
  • PaRes – A payment authorisation response returned by the card issuer.

Pass these parameters in the /authorise3d payment request to Adyen, as shown in the next step.

Step 4: Complete the 3D Secure payment

To complete the 3D Secure authenticated payment, make another request to the /authorise3d endpoint and pass the following parameters with the call:

  • merchantAccount – Your merchant account number.
  • md – A payment session identifier returned by the card issuer.
  • paResponse – Payment authorisation response returned by the card issuer on the previous step.
  • shopperIP – We strongly recommend that you provide shopperIP because it is used in a number of risk checks (like location-based and number of payment attempts checks).

The following example demonstrates how to complete the 3D Secure payment:

For information on available fields, refer to API Explorer.

Step 5: Present the payment result

Use the  resultCode from the /authorise or /authorise3d response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a webhook.

For card payments, you can receive the following resultCode values:

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment has been successful.
If you are using manual capture, you also need to capture the payment.
Cancelled The shopper cancelled the payment. Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.
Error There was an error when the payment was being processed. For more information, check the refusalReason field. Inform the shopper that there was an error processing their payment.
Refused The payment was refused. For more information, check the refusalReason field. Ask the shopper to try the payment again using a different payment method.

Testing 3D Secure payments

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

We recommend testing each Card Type.

To test how your integration handles different 3D Secure 2 authentication scenarios, use our test card numbers.

All our test cards use the following expiry dates and security codes:

Expiry Date CVC/CVV CID
03/2030 737 7373

When prompted for 3D Secure 2 text challenges, use the following credentials:

  • For mobile, use password: 1234
  • For web, use password: password
Card Type Card Number
Cartes Bancaires 4035 5014 2814 6300
Maestro 1 5000 5500 0000 0029
Mastercard 5454 5454 5454 5454
Visa 4917 6100 0000 0000

1 This card doesn't require a CVC.

When you make a payment request with these cards, you'll receive the following result codes depending on your integration:

  • RedirectShopper: You'll receive this result code if you are using the Redirect authentication.
  • IdentifyShopper: You'll receive this result code if you are using the Native authentication.
  • ChallengeShopper: You might get this result code after you submit the 3D Secure 2 device fingerprinting result in a Native authentication, indicating a challenge flow.

To test the web-based flow where the device fingerprinting step is skipped (because the issuer's ACS has not configured a threeDSMethodURL), and you get a ChallengeShopper resultCode immediately after submitting the payment request, use the following card:

Card Type Card Number
Visa 4212 3456 7891 0006

To test the frictionless flow, specify in your payment request:

  • amount.value: 12002

App-based integration

To test different authentication scenarios for app-based integration, use the following test cards:

Card number Authentication scenario
5201 2855 6567 2311 Basic text authentication
5201 2874 9905 2008 Basic single select
5201 2815 9233 1633 Basic multi select
5201 2888 2269 6974 Basic out-of-band (OOB) authentication
5201 2895 0084 3268 HTML OOB authentication
5201 2861 5377 1465 App single select then text authentication

Other scenarios

Card number Scenario
4199 3500 0000 0002 The card is not enrolled for 3D Secure transactions,
5201 2829 9900 5515 There was a technical error.

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