3DS 1 Fallback
If you are an integrator who only supports 3D Secure 1 (3DS 1), or if the Issuer does not support 3D Secure 2 (3DS 2), you can still implement Elavon’s Fraud Services solution. Transactions that need 3DS 1 authentication are appropriately redirected to the 3DS 1 authentication flow. Table 1 shows how the following fields in the authenticate request help the 3DS Server decide whether to follow 3DS 2 or 3DS 1 authentication flow: messageVersion
, clientStartProtocolVersion
, and clientEndProtocolVersion
Table 1: 3DS Server Fallback Strategy
messageVersion | clientStartProtocolVersion | clientEndProtocolVersion | 3DS Server Fallback Strategy |
---|---|---|---|
1.0.2 | 1.0.2 | 1.0.2 | Always use 3DS 1.0.2 |
1.0.2 | 1.0.2 | 2.1.0 | Always use 3DS 1.0.2 |
2.1.0 | 1.0.2 | 1.0.2 | Error response |
2.1.0 | 1.0.2 | 2.1.0 | Check support for 3DS 2.1. If supported, use 3DS 2.1 and if not supported, fall back to 3DS 1.0.2. |
2.1.0 | 2.1.0 | 2.1.0 | Check support for 3DS 2.1. If supported, use 3DS 2.1 and if not supported, return an error. |
note
messageVersion
is an optional field and if you do not manually specify a value in the authenticate request, the 3DS Server sets its default value to2.1.0
.- Currently, the 3DS Server supports 3DS 1 transactions for only Mastercard, Visa, and American Express. Please note the important dates from these card brands about 3DS 1.0.
- Mastercard
- Beginning October 1, 2021, stopping 3DS 1.0 support for non-participating issuers. Liability shift will not be available for impacted transactions after this date.
- From October 14, 2022, ending all support of 3DS 1.0.
- Visaopen_in_newLink opens new window
- Beginning October 16, 2021, stopping 3DS 1.0 support for non-participating issuers. Liability shift will not be available for impacted transactions after this date.
- From October 15, 2022, ending all support of 3DS 1.0.
- American Expressopen_in_newLink opens new window
- From October 14, 2022, ending all support of 3DS 1.0 (except in countries where it needs to be supported due to regulatory needs).
High-level steps for integration with Elavon’s 3DS Server with fallback support
- Complete the setup prerequisites
- Prepare your website’s payment page for 3DS authentication
- Collect cardholder data
- (Optional) Send cardholder’s card (acctNumber) to verify support for 3DS 1 or 3DS 2 (/3ds2/lookup)
- Send additional cardholder data for transaction authentication (/3ds2/authenticate)
- Send details to ACS for challenge completion and receive PaRes from the ACS
- Validate authenticate response (PaRes) with the 3DS Server (/3ds2/validate)
Step 1: Complete the setup prerequisites
To receive authentication credentials that you would need to test the different integration options in the sandbox environment, fill in the information requested in this form.
3D Secure 2 test credentials request formopen_in_newLink opens new window
error_outlinenote
Never expose your API key in the client-side code.
For more details on authentication mechanisms supported by Elavon for 3D Secure, see Authentication.
Set up a test and a production environment.
(Optional) Step 2: Prepare your website’s payment page for 3D Secure authentication
Perform this step if you are integrating directly with the 3DS Server and you want to implement a custom challenge-response receiver page. In that case, specify a custom URL in the notificationURL
field in the /3ds2/authenticate
request. Any notifications from the ACS will be redirected to this page, for example, the notification of the Payer Authentication Response (PaRes
). You must pass this URL as the TermUrl
when you redirect the customer to the ACS (acsURL
) for 3DS 1 authentication (see Step 6).
Before you begin 3D Secure authentication for a transaction, you must register an event listener code on your payment page. Perform this step only once; it is unnecessary to repeat it for every transaction.
note
If you are integrating using the Web SDK, you cannot specify a custom URL to handle notifications. In such scenarios, the 3DS Server receives all notifications from the ACS. For more details on Web SDK integration, see Web SDK Integration Overview.
Sample code to handle the PaRes receiver
/**
* Example code for PaRes receiver
*/
@RequestMapping(
path = "handle_3DS1_pares",
method = RequestMethod.POST,
consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
produces = MediaType.TEXT_HTML_VALUE)
@ResponseStatus(HttpStatus.OK)
@ApiOperation(value = "Receive PaRes and MD from ACS and call Elavon 3DS Server validate")
@ApiResponses(value = @ApiResponse(code = 200, message = "Successful Request"))
public ResponseEntity<RReq>(
@RequestParam String PaRes,
@RequestParam String MD)
throws Exception
{ try
{
//create 3DS Server /validate Request
ThreeDSValidateRequest request = ThreeDSValidateRequest.builder()
.messageId("sample_messageId")
.PaRes(PaRes)
.MD(MD)
.build();
//call 3DS Server validate call and POST request to /validate path with your client implementation
ThreeDSValidateResponse response = threeDSServerClient.validate(request);
//check if PaRes passed validation
if (response.getValid())
{
return ResponseEntity.ok(response.getRReq());
}
else
{
//handle PaRes failed validation
}
}
catch (Exception ex)
{
//handle any exceptions
}
}
Step 3: Collect cardholder data
To initiate a payment request for the cardholder’s purchase, collect the cardholder data entered on the merchant’s website.
Step 4: (Optional) Send cardholder’s acctNumber to verify support for 3DS 1 or 3DS 2 (/3ds2/lookup)
note
The /3ds2/lookup
call returns the 3DS version the acctNumber
supports and the BIN information. If you do not need this information, send the /3ds2/authenticate
request (See Step 5 ).
Use the POST /3ds2/lookup
call to send the acctNumber
to the 3DS Server. The 3DS Server first verifies if the issuer of the card supports 3DS 2. If 3DS 2 is not supported, the server checks if 3DS 1 fallback is enabled (i.e. clientStartProtocolVersion
= 1.0.2
) and whether the acctNumber
supports 3DS 1. When the server performs this check, the following scenarios are possible.
Sample URLs
Test:https://uat.gw.fraud.eu.elavonaws.com/3ds2/lookupopen_in_newLink opens new window
Production:https://gw.fraud.elavon.com/3ds2/lookupopen_in_newLink opens new window
Scenario 1: Client supports only 3DS 1
When the client supports only 3DS1, set the values of both clientStartProtocolVersion
and clientEndProtocolVersion
fields to 1.0.2
in the /3ds2/lookup
request. The 3DS Server checks if the acctNumber
supports 3DS 1, and if supported, it returns the following /3ds2/lookup
response:
Example request
{
"messageId": "sample-test",
"acctNumber": "40XXXXXXXXXX0005",
"doBinLookup" : false,
"clientStartProtocolVersion": "1.0.2",
"clientEndProtocolVersion" : "1.0.2"
}
Example response
{
"messageId": "sample-test",
"threeDSServerTransID": "67b76006-c6a6-4956-915b-0df41fc47b83",
"dsStartProtocolVersion": "1.0.2",
"dsEndProtocolVersion": "1.0.2",
"acsStartProtocolVersion": "1.0.2",
"acsEndProtocolVersion": "1.0.2",
"serverStartProtocolVersion": "1.0.2",
"serverEndProtocolVersion": "2.1.0"
}
See Step 5 - Send additional cardholder data for transaction authentication (/3ds2/authenticate
) for further steps in this flow.
Scenario 2: Client supports only 3DS 2
When the client supports only 3DS 2, set the values of both clientStartProtocolVersion
and clientEndProtocolVersion
fields to 2.1.0
in the /3ds2/lookup
request. The 3DS Server checks if the acctNumber
supports 3DS 2, and if supported, it returns the /3ds2/lookup
response.
For further steps in this flow, see Direct integration with the 3DS Server.
Scenario 3: Client supports 3DS 2 and 3DS 1 fallback is enabled
In this scenario, the value of clientStartProtocolVersion
is set to 1.0.2
and the value of clientEndProtocolVersion
is set to 2.1.0
or later.
If the
Sample lookup request and responseacctNumber
supports 3DS 2, the 3DS Server returns the/3ds2/lookup
response.For further steps in this flow, see Direct integration with the 3DS Server.
If the
acctNumber
does not support 3DS 2 but supports 3DS 1, the 3DS Server returns the following/3ds2/lookup
response.See Step 5 - Send additional cardholder data for transaction authentication (
/3ds2/authenticate
) for further steps in this flow.Example request
Description of lookup request and response parameters{ "messageId": "sample-test", "acctNumber": "4900000000000003", "doBinLookup" : false, "clientStartProtocolVersion": "1.0.2", // Oldest 3DS version supported by the client. "clientEndProtocolVersion" : "2.1.0" // Most recent 3DS version supported by the client }
Example response if 3DS 1 fallback is enabled and the acctNumber supports 3DS 1
Description of lookup request and response parameters{ "messageId": "sample-test", "threeDSServerTransID": "f00a98c3-2d39-4b33-a6f2-1759d2ede222", "dsStartProtocolVersion": "1.0.2", "dsEndProtocolVersion": "1.0.2", "acsStartProtocolVersion": "1.0.2", "acsEndProtocolVersion": "1.0.2", "serverStartProtocolVersion": "1.0.2", // Oldest 3DS version supported by the 3DS Server. "serverEndProtocolVersion": "2.1.0" // Most recent 3DS version supported by the 3DS Server. }
If the
acctNumber
does not support 3DS 2 or 3DS 1The 3DS Server first attempts 3DS 2 authentication and then checks for 3DS 1 support. When both checks are false, it returns an error.
Example response if 3DS 1 fallback is enabled, but the acctNumber does not support 3DS 1 or 3DS 2 (i.e., an error)
{ "messageId": "sample-test", "serverStartProtocolVersion": "1.0.2", "serverEndProtocolVersion": "2.1.0", "error": { "messageType": "Erro", "messageVersion": "2.1.0", "threeDSServerTransID": "67b76006-c6a6-4956-915b-0df41fc47b83", "errorCode": "305", "errorComponent": "S", "errorDescription": "Account number not supported", "errorDetail": "Account number not supported by 3DS. Validate the account number: 40XXXXXXXXXX0005" } }
Step 5: Send additional cardholder data for transaction authentication
Use the POST /3ds2/authenticate
call to send additional cardholder details to the 3DS Server. The messageVersion
(optional), clientStartProtocolVersion
, and clientEndProtocolVersion
field values in the authenticate request help the 3DS Server to decide whether to process the transaction using 3DS 2 or 3DS 1 protocol.
To enable fallback to 3DS 1, set the value of clientStartProtocolVersion
to 1.0.2
and the value of clientEndProtocolVersion
to 2.1.0
in the authenticate request. If 3DS 1 fallback is enabled, the 3DS Server converts the aReq to VEReq and completes the 3DS 1 verify enrollment flow.
- VEReq (Verify Enrollment Request): determines whether 3DS 1 authentication is available for a particular PAN/
acctNumber
. - VERes (Verify Enrollment Response): advises the merchant whether 3DS 1 authentication is available for a particular PAN/
acctNumber
.
Sample URLs
Test:https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticateopen_in_newLink opens new window
Production:https://gw.fraud.elavon.com/3ds2/authenticateopen_in_newLink opens new window
The following scenarios are possible when you send the /3ds2/authenticate
request.
Scenario 1: Client only supports 3DS 1
If you want the 3DS Server to always fallback to 3DS 1 for transaction authentication, you must set the following fields to 1.0.2
in the authenticate request: messageVersion
and clientStartProtocolVersion
.
important
The default value of the messageVersion
field is 2.1.0
. If you don’t set this field to 1.0.2
, but you set the clientStartProtocolVersion
field to 1.0.2
, the 3DS Server does not attempt a fallback to 3DS 1 and returns an error response.
In the background, the 3DS Server will convert the 3DS 2 authenticate request (aReq) to 3DS 1 Verify Enrollment Request (VEReq) and send it to the ACS to complete the 3DS 1 verify enrollment call. The 3DS Server will convert the Verify Enrollment Response (VERes) from the ACS to 3DS 2 authentication response (aRes) and send it to the client. The aRes returns the acsURL
that the client will redirect the customer to for challenge completion. The aRes also returns the PaReq
, TermUrl
, and MD
that the client will send to the ACS in step 6 for 3DS 1 authentication.
Example 3DS 1 authentication request
{
"messageId": "sample-test",
"aReq":
{
"messageVersion": "1.0.2",
"threeDSServerTransID": "ec9a5b6c-bc55-4296-aa3b-d1d762e655f2",
"acctNumber": "4000020000000000",
"cardExpiryDate": "2312",
"purchaseAmount": "101",
"purchaseCurrency": "978",
"purchaseExponent": "2",
"purchaseDate": "20170316141312",
"messageCategory": "01",
"transType": "01",
"threeDSRequestorAuthenticationInd": "01",
"deviceChannel": "02",
"browserAcceptHeader": "text/html,application/xhtml+xml,applicati...",
"browserJavaEnabled": true,
"browserLanguage": "en",
"browserColorDepth": "48",
"browserScreenHeight": "400",
"browserScreenWidth": "600",
"browserTZ": "-240",
"browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47..",
"notificationURL" : "http://merchantURL/handle_3DS1_pares",
},
"clientStartProtocolVersion": "1.0.2",
"clientEndProtocolVersion": "1.0.2"
}
note
- Set the
notificationURL
to a location where you want to receive the PaRes (payer authentication response). If you do not specify a custom URL, by default, theTermUrl
is set to the 3DS Server URL https://gw.fraud.eu.elavonaws.com/notify/challenge_notifyopen_in_newLink opens new window in the aRes. However, you can still send a custom URL as theTermUrl
for ACS redirect in step 6 even if you did not set anotificationURL
in the authenticate request. Use the following 3DS Server URLs: - Test environment: https://uat.gw.fraud.eu.elavonaws.com/notify/challenge_notify
- Production environment: https://gw.fraud.elavon.com/notify/challenge_notify
- If you are sending the
/3ds2/authenticate
request for a service provider merchant (a merchant who does not process their payments with Elavon), you must send the following field values in the aReq request body. The 3DS Server returns an error if any of these field values are missing in the request. - Acquirer Merchant Id (
acquirerMerchantID
) - Acquirer BIN (
acquirerBIN
)
For merchants acquired by Elavon, the 3DS Server appends these fields in the authenticate request that it sends to the ACS (Issuer). See the API Reference page for the field descriptions.
Example 3DS 1 authentication response
{
"messageId": "sample-test",
"aRes": {
"messageType": "VERes",
"messageVersion": "1.0.2",
"threeDSServerTransID": "1a6076cf-eced-447a-a136-585c5ae82d06",
"acsURL": "https://uat.acs.fraud.eu.elavonaws.com/acs/challenge/VISA",
"xid": "549855BF4A.33C824-T1"
},
"PaReq": "eJxVUmFvmzA...",
"TermUrl": "http://merchantURL.com/handle_3DS1_pares",
"MD": "encoded64bitPaReqMsgIDandetc"
}
Scenario 2: Client only supports 3DS 2
In this scenario, the clientStartProtocolVersion
and clientEndProtocolVersion
fields are set to 2.1.0
or later. The 3DS Server authenticates the transaction using the 3DS 2 authentication flow.
note
You can optionally set the messageVersion
field to 2.1.0
. If you do not include this field in the authenticate request, the 3DS Server sets the value to 2.1.0
by default.
For further steps in this flow, see Direct integration with the 3DS Server.
Scenario 3: Client supports 3DS 2 and fallback to 3DS 1 is enabled
If you want to enable 3DS 1 fallback (i.e., clientStartProtocolVersion
= 1.0.2
and clientEndProtocolVersion
= 2.1.0
), you can optionally set the messageVersion
field to 2.1.0
. If you do not include this field in the authenticate request, the 3DS Server sets the value to 2.1.0
by default.
note
If you enable 3DS 1 fallback but you set the
messageVersion
field to1.0.2
, the 3DS Server only attempts a fallback to 3DS 1.If the 3DS 2 service encounters an error and 3DS 1 fallback is enabled, the 3DS Server does not fail the transaction and begins the 3DS 1 authentication of the transaction. The fallback is triggered only for valid authentication requests (includes all required fields and has valid field values) that failed.
The 3DS Server returns one of the following responses:
If the
acctNumber
supports 3DS 2, the 3DS Server authenticates the transaction using the 3DS 2 authentication flow. For further steps in this flow, see Direct integration with the 3DS Server.If the
acctNumber
does not support 3DS 2 but 3DS 1 fallback is enabled, then the 3DS Server authenticates the transaction using the 3DS 1 authentication flow.In the background, the 3DS Server will convert the 3DS 2 authenticate request (aReq) to 3DS 1 Verify Enrollment Request (VEReq) and send it to the ACS to complete the 3DS 1 verify enrollment call. The 3DS Server will convert the Verify Enrollment Response (VERes) from the ACS to 3DS 2 authentication response (aRes) and send it to the client. The aRes returns the
acsURL
that the client will redirect the customer to for challenge completion. The aRes also returns thePaReq
,TermUrl
, andMD
that the client will send to the ACS in the next step (Send details to ACS for challenge completion and receive PaRes from the ACS) for 3DS 1 authentication.See the example request and response in Step 5 Scenario 1.
Scenario 4: Client supports 3DS 2 and fallback to 3DS 1 is also enabled, but acctNumber does not support 3DS 2 or 3DS 1
The 3DS Server returns the following error response.
Example response
{
"messageId": " db09f94a-12eb-44e9-ad3b-87a23370b205",
"error": {
"messageType": "Erro",
"messageVersion": "2.1.0",
"threeDSServerTransID": "8ef7c99e-72e5-4d66-8a84-229cd9f925d9",
"errorCode": "305",
"errorComponent": "S",
"errorDescription": "Invalid transaction data",
"errorDetail": "Account number not enrolled in 3DS 1.0. Please register card with Issuer to proceed.",
"errorMessageType": "AReq"
}
note
Elavon could not perform a 3DS check for this transaction. Integrator can still process the transaction at their own risk and liability.
Step 6: Send details to ACS for challenge completion
If the acctNumber
support 3DS 1, perform this step to complete 3D Secure (3DS) Authentication. The challenge and validation flow for 3DS 1 is different from the 3DS 2 flow. In 3DS 1, it is the client’s responsibility to redirect the customer’s browser to the acsURL
for challenge completion. The ACS handles the challenge completion directly with the cardholder and will send the Payer Authentication Response (PaRes
) back to the client for validation.
To initiate a challenge, the client should FORM-POST these three fields to the
acsURL
:PaReq
,TermUrl
, andMD
via a redirect from the user’s browser.
ThePaReq
andMD
contain encrypted data required for the ACS to complete authentication. TheTermUrl
is the return address that the ACS will redirect the customer to after the 3DS authentication. As mentioned in the prerequisites, the client can also pass in the URL of their challenge-response receiver page as theTermUrl
.After the cardholder authenticates with the issuer directly, the ACS will send the cardholder back to the page provided in the
TermUrl
with an HTTP Post. The ACS will also send the Payer Authentication Response (PaRes
) and the MD to theTermUrl
. Note that the ACS sends the PaRes to theTermUrl
even if the authentication fails.
Step 7: Validate the PaRes to obtain authentication results
Following authentication, the ACS will redirect the cardholder to the TermUrl
sent in step 6 for challenge completion. To validate the PaRes
and obtain the final authentication result, send the /3ds2/validate
request to the 3DS Server and pass in the PaRes
and MD
in the request body.
In the background, the 3DS Server will complete the validate PaRes call. The 3DS Server will decode the PaRes
and validate the response against the MD
to complete 3DS validation. After validation, the 3DS Server will return the results of the validation (rReq) and the transaction status (transStatus
) for the client to complete the transaction. Depending on the validation result, the client can authorize or decline the transaction.
POST /3ds2/validate
Sample URLs
- Test:https://uat.gw.fraud.eu.elavonaws.com/3ds2/validateopen_in_newLink opens new window
- Production:https://gw.fraud.elavon.com/3ds2/validateopen_in_newLink opens new window
Sample request
{
"PaRes" : "JzVWFmPo0qyCXszacKQNUK/b8L3vRy2rRuHX9Pg+……",
"MD" : "eyJwYVJlcU1zZ0l…."
}
note
The PaRes
and MD
are long string values. The above sample request has incomplete values.
Sample response of a successful validation
{
"messageId": "sample-test",
"threeDSServerTransID": "1a6076cf-eced-447a-a136-585c5ae82d06",
"valid": true,
"xid": "574FADF181.D4993A-T1",
"cavvAlgorithm": "2",
"rReq": {
"messageType": "RReq",
"messageVersion": "1.0.2",
"threeDSServerTransID": "1a6076cf-eced-447a-a136-585c5ae82d06",
"authenticationValue": "rPTpf2gUHkTkoSOmN5aTJkfcgDs=",
"eci": "05",
"transStatus": "Y"
}
}
For more information on liability shift and next steps for merchants for different transStatus
, see Test your integration. Note that in a 3DS 1 transaction, the response returns the transStatus
value as either of the following: Y
, N
, U
, A
. The eci
and authenticationValue
fields are returned in the response only for transStatus
= Y
or A
.
Sample response of a failed validation
{
"messageId": "sample-test",
"threeDSServerTransID": "2ac6ae1b-e388-4a4d-9842-47bda005936a",
"valid": false
}
Field descriptions of 3DS 1 specific elements
Field Name | Description | Required | Length | Data Type |
---|---|---|---|---|
messageType | Identifies the type of message that is passed. Valid values for 3DS 1:
| Yes | 5 | String |
messageVersion | The 3DS protocol version used by all components to process the 3D Secure transaction. Set by the 3DS Server, which originates the protocol with the authentication request message. error_outline important If you want the 3DS Server to always fall back to 3DS 1, set it to Valid values:
2.1.0 | Yes | 5-8 | String |
xid | Unique purchase ID. Returned from the 3DS Server. | Yes | 28 | base64 |
enrolled | Indicates whether the card is enrolled in 3DS 1 or not. Returned from the 3DS Server. Valid values:
| Yes | NA | Boolean |
acsURL | The ACS URL used to complete the 3DS 1 challenge flow. The client must redirect the cardholder to this URL for challenge completion. | Conditional | Max 2048 | String |
PaReq | Payer authentication request The PaReq is sent to the ACS by the 3DS Server, which uses the information in the aReq and converts it to the PaReq. It has the data required to attempt cardholder authentication. | Yes | ANS | base64 |
TermUrl | Indicates the URL that will be notified of the challenge result by ACS. The TermUrl is the URL sent in the aReq.notificationURL field in the authentication request. | Yes | NA | String |
MD | Merchant data A 64bit encoded JSON unique reference to identify if the 3D Secure request is genuine. It is sent to the ACS for challenge completion. | Conditional | 0-1024 ANS | String |
cavv | Cardholder Authentication Verification Value. In case of a direct integration with the 3DS Server, the server returns an authenticationValue field instead of cavv | Conditional | 28 | base64 |
cavvAlgorithm | Indicates the algorithm used to generate the Cardholder Authentication Verification Value. error_outline note If the | Conditional | 0-1 | String |
eci | Electronic commerce indicator Payment Scheme specific element that represents the value of the ECI, as determined by the ACS. error_outline note Required for Visa and MasterCard transactions when the value of | Conditional | 0-2 | String |
statusCode | Indicates the transaction authorization status of the transaction. Valid values:
| Yes | 1 | String |
PaRes | Payer authentication response The PaRes message is sent by the ACS in response to the PaReq, regardless of whether authentication is successful. | Yes | NA | base64 |