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:
- Let Adyen handle PSD2 compliance by default.
- Configure rules using Dynamic 3D Secure.
- 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:
- Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.
- 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
resultCode
s 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 topaRequest
and holds the 3D Secure request data for the issuer.MD
– corresponds tomd
. A payment session identifier returned by the card issuer. Note that it must be uppercase in the POST message to the issuer.TermUrl
– corresponds totermUrl
. 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 provideshopperIP
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.