Direct integration to 3DS Server
On this page:
Use the information on this page to support 3D Secure 2 authentication on your website. In this integration option, all requests are sent by your server. A transaction can go through a frictionless flow or a challenge flow depending on the authentication results from the issuer. To support these flows, you must build your client-side and server-side implementations.
To use the 3DS Web SDK, see 3DS Web SDK Overview.
High-level steps for integrating with Elavon’s 3DS server for a transaction authentication
Verify the authentication response received from Elavon’s 3DS Server[/
If the issuer confirms the authentication as successful, authorize the cardholder’s transaction
Authentication workflows
Figure caption: Frictionless and challenge workflow in a server-to-server integration
Prerequisites for sending the cardholder data for 3D Secure 2 authentication
To request authentication credentials that you would need to test the different integration options in the sandbox environment, fill in the information requested in this form.
open_in_new3D Secure 2 test credentials request formLink opens new window
info_outlineimportant
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.
3D Secure 2 Authentication steps for each transaction
Step 1: Collect cardholder data
To initiate a payment request for the cardholder’s purchase, collect the cardholder data entered on the merchant’s website.
(Optional) Step 2: Send cardholder’s card/account number to verify support for 3D Secure 2 (/3ds2/lookup
)
Send the card holder’s card/account number to Elavon’s 3DS Server to:
verify if the card used by the cardholder for the transaction supports 3D Secure 2
retrieve key characteristics of the card used in the transaction such as the card BIN, scheme, brand, country, and currency where the card has been issued, if the card is a debit or a credit card, etc. The BIN is the first four, six, or more digits of the card number. The
/3ds2/lookup
request uses the BIN information to scan an internal repository of data to retrieve more details about the card being used.
The BIN lookup parameters along with the fact the card supports 3DS 2 authentication can help you understand which version of the 3D Secure 2 the card supports.
If you do not send the /lookup
request and send the (/authenticate
(Step 4)) request directly, the /authenticate
response will return an error message if the issuer does not support the requested 3D Secure version.
Use the following links for a sample /3ds2/lookup
request, response, and parameters description:
- Sample request and response
- Description of request and response parameters
- Test scenarios - Sample /3ds2/lookup scenarios
(Optional) Step 3: Verify the /3ds2/lookup
response
The 3DS Server uses the ACS Start Protocol Version
, ACS End Protocol Version
, DS Start Protocol Version
, and DS End Protocol Version
returned in the /lookup
response to verify that the ACS and the DS support the 3DS protocol version used by the 3DS Server. It uses the ACS Information Indicator
to identify the features that the account supports.
Verify the /3ds2/lookup
response and use the scenarios in table 1 to help you decide the next step.
Table 1: /lookup response scenarios
Scenario | Next Step |
---|---|
Scenario 1: If the /3ds2/lookup response does not have the version fields (dsStartProtocolVersion , dsEndProtocolVersion , acsStartProtocolVersion , acsEndProtocolVersion ) or the values of these fields are 1.0.2 , it means that the card number (PAN) does not support 3DS 2 authentication. | You cannot proceed with 3DS 2 authentication for this transaction. The 3DS server returns an error message. |
Scenario 2: If the /3ds2/lookup response contains the version fields (dsStartProtocolVersion , dsEndProtocolVersion , acsStartProtocolVersion , acsEndProtocolVersion ) and their values are either 2.1.0 or later, but the threeDSMethodURL field is not present. | Proceed to step 4. If the threeDSMethodURL field is not present, it means that the ACS does not support 3DS Method. In this scenario, you can directly send the /3ds2/authenticate request. |
Scenario 3: If the /3ds2/lookup response contains the version fields (dsStartProtocolVersion , dsEndProtocolVersion , acsStartProtocolVersion , acsEndProtocolVersion ), their values are either 2.1.0 or later, and the threeDSMethodURL field is also present. | If the threeDSMethodURL field is present, invoke the 3DS Method before you send the /3ds2/authenticate request. The browser will need to connect to the ACS (or a designated entity) mentioned in the threeDSMethodURL value to gather browser and device information. To facilitate browser and device information collection, render a hidden HTML iframe in the cardholder’s browser (see sample iframe code for contents of the iframe). In this iframe, create a form that is auto-submitted when the cardholder’s response is loaded in the iframe. The auto submission of this form will post the threeDSMethodData field value to the threeDSMethodURL . Proceed to step 4 when you receive either a successful completion notification from the 3DS Server (or notification on the custom URL, if you have set one) or if you do not receive a response after 10 seconds of sending the HTTP POST form. This step is optional, but we strongly recommend you to perform this step to increase the chances of a frictionless authentication. |
Sample iframe code
<html>
<body onload='document.forms[0].submit()'>
<form method=POST action='value of the threeDSMethodURL in the /3ds2/lookup response'>
<input type=hidden name='threeDSMethodData' value='value of the threeDSMethodData field in the /3ds2/lookup response'>
</form>
</body>
</html>
Step 4: Submit cardholder data to the 3DS Server to initiate the 3DS authentication process (/3ds2/authenticate
)
If the card used in the transaction supports 3D Secure 2, submit the required authentication information to Elavon’s 3DS Server. The 3DS Server in turn creates an authentication request and sends it to the ACS.
Review table 2 to understand how these three fields in the /authenticate
request help the 3DS Server to decide whether to follow 3DS 2.2 or 3DS 2.1 authentication flow: messageVersion
, clientStartProtocolVersion
, and clientEndProtocolVersion
.
Table 2: 3DS Server Fallback Strategy
messageVersion | clientStartProtocolVersion | clientEndProtocolVersion | 3DS Server Fallback Strategy |
---|---|---|---|
1.0.2 | 1.0.2 | 1.0.2 | 3DS Server returns an error. |
1.0.2 | 1.0.2 | 2.1.0 or 2.2.0 | 3DS Server returns an error. |
2.1.0 or 2.2.0 | 1.0.2 | 1.0.2 | 3DS Server returns an error. |
2.1.0 | 1.0.2 | 2.1.0 or 2.2.0 | Check support for 3DS 2.1. If not supported, the 3DS Server returns an error. |
2.1.0 | 2.1.0 | 2.1.0 | Check support for 3DS 2.1. If not supported, return an error. |
2.1.0 | 2.1.0 | 2.2.0 | Check support for 3DS 2.1. If not supported, return an error. |
2.2.0 | 1.0.2 | 2.2.0 | Check support for 3DS 2.2 first. If not supported, check support for 3DS 2.1. If 3DS 2.1 is not supported, the 3DS Server returns an error. |
2.2.0 | 2.1.0 | 2.1.0 | Error response |
2.2.0 | 2.2.0 | 2.2.0 | Check support for 3DS 2.2. If not supported, return an error. |
2.2.0 | 2.1.0 | 2.2.0 | Check support for 3DS 2.2 first. If 3DS 2.2 is not supported, fall back to 3DS 2.1. If 3DS 2.1 is 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
.- If the 3DS Server falls back the request to
2.1.0
, the issuer ignores all fields that are specific only to the 3D Secure2.2.0
.
- If the 3DS Server falls back the request to
The request will not fall back from
2.2.0
to2.1.0
if you send a value specific to the
2.2.0
spec only in an existing field (a field that was present in the2.1.0
spec as well). For example, if you set the field value of thethreeDSRequestorAuthenticationInd
field (present in both the2.1.0
and the2.2.0
spec) to07
(billing agreement). Here the field value07
is specific to2.2.0
only.if one or more fields that are required in the
2.1.0
spec but are optional in the2.2.0
spec are missing in the authentication request. For example, fordeviceChannel = 02
, thebrowserColorDepth
,browserScreenHeight
,browserScreenWidth
andbrowserTZ
fields are always required, but in the2.2.0
spec these fields are optional ifbrowserJavascriptEnabled = false
.
Use the following links to refer to the sample authentication request, response, and parameters description.
- Sample request and response
- Description of request and response parameters
- Test scenarios - Sample /3ds2/authenticate scenarios
To increase the chances of successful authentication, include information for all required and optional fields in the authentication request you send to the 3DS Server. However, do not send dummy data if you do not have data for an optional field.
note
By default, the 3DS Server receives the callbacks from the ACS. But if you want to opt-out from the default challenge callback functionality and implement your own challenge-response landing page, set the value of the notificationURL
field in the /3ds2/authenticate
request to a custom URL, where you can receive and monitor notifications. In such cases, you are responsible for handling notifications and continuing with the 3DS flow. To fetch the challenge result data from the ACS, you will have to send the /3ds2/validate
request (step 7b) instead of the /3ds2/challenge_result
request.
Step 5: Verify the 3DS authentication response from the 3DS Server
Verify the value of the transStatus
field in the /3ds2/authenticate
response sent by the 3DS Server because it determines your next step. Review the information in table 3 to understand the next steps for each transStatus
value.
If the acctNumber
or the issuer doesn’t support 3D Secure 2, the 3DS Server returns an error.
Table 3: Description of the transStatus field value in /authenticate response
transStatus | Description | Liability shift | Next step | Example scenario |
---|---|---|---|---|
Y | Issuer has authenticated the customer’s data. You can use the transStatus , authenticationValue , and eci field values to authorize the transaction. The flow is considered frictionless and the 3DS processing will end at this step. | Card issuer | Merchant can use the eci and authenticationValue in the authentication response to proceed to card authorization. | You get this value in case of a successful authentication or a frictionless flow. |
A | Issuer has not authenticated the transaction, but a proof of authentication attempt (authenticationValue ) was generated. You can use the transStatus , authenticationValue , and eci field values to authorize the transaction. The 3DS processing will end at this step. | Card issuer | Merchant can use the eci and authenticationValue in the authentication response to proceed to card authorization. | You get this value in case of an attempted authentication. |
I | Issuer acknowledges that the request was sent for informational purposes only and did not need a challenge. | Not applicable | Merchant should store the authenticationValue and eci field values if included in the response. | You get this value when you send the request only for information and do not request for authentication. To indicate this in the authentication request, you sent a value of 05, 06, or 07 in the threeDSRequestorChallengeInd field. |
C | Issuer needs more information to authenticate the cardholder. The flow is considered a challenge flow. Proceed to step 6. | Not applicable; Authentication in progress | Merchant should proceed with the challenge to get the final authentication result. | You get this value when the issuer needs more authentication data from the cardholder. |
N | Issuer has not authenticated the transaction, or could not verify the account, or denied the transaction. | No liability shift | If you get this value, verify the value in the transStatusReason field. Based on the value received, you can do either of the following:
| You get this value in case of authentication processing errors such as when the cardholder fails all challenges to prove cardholder identity. |
U | Issuer has not authenticated the transaction or verified the account due to a technical or another problem. | No liability shift | If you get this value, verify the value in the transStatusReason field. Based on the value received, you can do either of the following:
| You get this value in case of technical errors such as when the ACS is not reachable. |
R | Issuer is rejecting the authentication or account verification and requesting that authorization not be attempted. | No liability shift | If you get this value, verify the value in the transStatusReason field. Based on the value received, you can do either of the following:
| You get this value in case the issuer rejects authentication and requests that authorization should not be attempted. |
note
The liability shift is only for disputed transactions or chargebacks. Use the following information related to liability shift and next steps for merchants as a reference. These can differ for each card scheme and each issuer might have different criteria for liability shift.
Step 6: If transStatus = C
, create an iframe to facilitate the challenge process between the issuer and the cardholder
Perform this step only if you received transStatus = C
in Step 5.
The challenge process requires the cardholder to send the authentication data to the issuer directly. Therefore, to challenge the cardholder, you need to create an iframe and populate it with the creq
value received in the authentication response. This iframe will autosubmit the creq
to the acsURL
.
The issuer will validate the creq
data and create an authentication user interface (ACS UI) that is loaded on the iframe.
The cardholder will enter the authentication data requested by the issuer in the form that is loaded on this iframe and submit the authentication data to the issuer. The issuer will verify the authentication data and send the challenge response to the browser in an HTML form that will be auto-submitted to the notificationURL
field value mentioned in the authentication request sent by the merchant (/3ds2/authenticate
).
note
By default, the 3DS Server receives the callbacks from the ACS. But if you want to opt-out from the default challenge callback functionality and implement your own challenge-response landing page, set the value of the notificationURL
field in the /3ds2/authenticate
request to a custom URL, where you can receive and monitor notifications. In such cases, you are responsible for handling notifications and continuing with the 3DS flow. To fetch the challenge result data from the ACS, you will have to send the /3ds2/validate
request (step 7b) instead of the /3ds2/challenge_result
request.
To facilitate the challenge process, perform the following steps:
Select the size of the HTML iframe from one of the window sizes specified in the
challengeWindowSize
data element:If you are building a static UI with client-side restriction on the iframe sizing, then use one of the following options for the
challengeWindowSize
parameter:- 01 = 250 x 400
- 02 = 390 x 400
- 03 = 500 x 600
- 04 = 600 x 400
If you are opting for a responsive design that lets the issuer to dynamically scale the content, then use the following option for the
challengeWindowSize
parameter:- 05 = Full screen
Copy the creq value from the authentication response. The creq request JSON object should be Base 64 encoded.
Sample creq JSON encoded data
eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLCJhY3NUcmFuc0lEIjoiODRiMmU5YTYtYjEwMi00OGRiLTkzZjAtNjBlZmFmYjk5Nzc0In0=
Render an HTML iframe in the cardholder’s browser, and generate an HTTP POST through the iframe to the
acsURL
that was received in the authentication response message.Sample iframe code
<html> <body onload='document.forms[0].submit()'> <form method=POST action='https://value-of-the-acsURL-in-the-/3ds2/authenticate-response'> <!-- creq value is the encrypted value of the creq field in the /3ds2/authenticate response --> <input type=hidden name='creq' value= 'eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLCJhY3NUcmFuc0lEIjoiODRiMmU5YTYtYjEwMi00OGRiLTkzZjAtNjBlZmFmYjk5Nzc0In0='> </form> </body> </html>
Step 7: Verify the challenge completion response using either step 7a or step 7b
Step 7a: If you sent the 3DS Server URL as the notificationURL in the /3ds2/authenticate
request, verify the challenge response /3ds2/challenge_result/{threeDSServerTransID}
If you received transStatus = C or D
in the /authenticate
response, verify the challenge completion response from the 3DS Server using the threeDSServerTransID
value from the authentication response (/3ds2/authenticate
).
note
By default, the 3DS Server receives the callbacks and notifications on the notificationURL
populated by the 3DS Server in the authentication request (/3ds2/authenticate
).
Use the /3ds2/challenge_result/{threeDSServerTransID}
request to retrieve the result of the challenge completion. Use the following links to see a sample challenge result request, response, and parameters description:
After you verify the challenge result, close the challenge window by refreshing the parent page and removing the HTML iframe.
If the challenge completion result is successful (transStatus = Y
), use the transStatus
, authenticationValue
, and eci
field values to complete the 3DS authentication process.
Step 7b: If you specified a different notificationURL
in the /3ds2/authentication
request, verify the challenge response from the ACS ( /3ds2/validate
)
If you opted out from the default challenge callback functionality and implemented your own challenge-response landing page by setting the value of the notificationURL
field in the /3ds2/authenticate
request to a custom URL, you must monitor notifications sent by the ACS to this page. To fetch the challenge result data from the ACS, send the /3ds2/validate
request (step 7b) instead of the /3ds2/challenge_result
request (step 7a).
note
Before you send the /3ds2/validate
request, the landing page should accept POST request from the ACS with FORM parameter named cres
. After you get the cres
value from the ACS, use the messageId
and the cres
in the /3ds2/validate
request. The /3ds2/validate
response will have the rReq
data with the challenge result or the final authentication result. You do not need to send any additional request to the 3DS Server i.e., a /3ds2/challenge_result
request (step 7a).
Use the following links to see a sample validate challenge result request, response, and parameters description:
If the challenge completion result is successful (transStatus = Y
), use the transStatus
, authenticationValue
, and eci
field values to complete the 3DS authentication process.