Overview
A challenge authenticates the identity of the customer. This topic describes implementing the 3D-Secure Authentication Challenge for 3D-Secure V1 and V2, which is a step in the 3D-Secure Authentication process of a:
- Payment flow of a Server-to-Server integration.
- Authorize3d flow of a 3DS MPI-Only REST integration.
The challenge flows for 3D-Secure v1 and v2 are different, as described below.
Determine the Version of 3D-Secure Challenge to Perform
Determine which version to perform as follows:
- Only perform a challenge when:
transactionStatus
="REDIRECT"
(returned from the payment (or authorize3d) request). - The response from the payment (or authorize3d) request may also include:
cascadedTo3Dv1
=true
This indicates that the 3Dv2 payment (or authorization) request failed for some technical reason, but the Nuvei gateway has “downgraded” it to a 3Dv1 payment (or authorization) request and continues to process it as a 3Dv1 payment (or authorization) flow. In such a case, the payment (or authorization) may still be able to pass as a 3D-Secure v1 request. For more details, see Downgrading (Cascading) from 3D-Secure v2 to v1. - Determine the challenge version:
- Perform a Challenge for 3D-Secure v1 if:
v2supported
<>true
(returned from the initPayment request)
- OR
cascadedTo3Dv1
=true
(returned from the payment (or authorize3d) request)
- Perform a Challenge for 3D-Secure v2 if:
- (
v2supported
=true
) and (cascadedTo3Dv1
<>true
)
- (
- Perform a Challenge for 3D-Secure v1 if:
Challenge for 3D-Secure v1
Request the issuer to perform a challenge as follows:
- Post the following form to the
acsUrl
URL (the Issuer Authentication URL) by concatenating the following HTTP GET fields (hidden input fields) onto theacsUrl
URL as shown in the example below (case-sensitive!):
Example
-
<body OnLoad='OnLoadEvent();'> <form action="<value of paymentOption.card.threeD.acsUrl>" method="POST" id="threeD" name="threeD"> <input type="hidden" name="PaReq" value="<paymentOption.card.threeD.paRequest value from the first payment request>"> <input type="hidden" name="TermUrl" value="<your URL to receive the response in the redirect back>"> <input type="hidden" name="MD" value="<your value to identify the session>"> <!-- this is optional --> </form> <script language="Javascript"> document.getElementById("threeD").submit(); </script> </body>
Parameter Description PaReq
(String) (Required)For the paReq
field (note the capitalization), use thepaymentOption.card.threeD.paRequest
value, returned in the previous /payment (or /authorize3d) response step).TermUrl
(String) (Required)The URL that the issuer should redirect your customer to, at the end of the 3D-Secure authentication process. MD
(String) (Optional)Optional merchant data that can be posted back to the TermUrl
at the end of the 3D-Secure authentication process.
Example with Sample Values
-
<!-- with sample values: <form action="https://3dsn.sandbox.nuvei.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?" method="POST" id="threeD" name="threeD"> <input type="hidden" name="PaReq" value="c2FtcGxlIFBhUmVzLiBhIHJlYWwgUGFSZXMgd2lsbCBiZSBlbmNvZGVkIGJpbmFyeSBjaXBoZXI="> <input type="hidden" name="TermUrl" value="https://www.yourdomain.com/3dsResponse"> <input type="hidden" name="MD" value="1234567890"> </form> -->
-
- The customer is redirected to the issuer’s challenge page and performs the challenge.
Upon completion of the challenge process, the issuer redirects the customer to theTermUrl
(that you provided in the form above) and returns a base64-encodedPaRes
field containing the 3D-Secure response data to theTermUrl
.
(You need thePaRes
value in the next step to send thepaResponse
field.) - Continue to the next step:
- For a payment flow: Final Payment Request.
- For an authorize3d flow: Verify the 3D-Secure Authorization Result.
Challenge for 3D-Secure v2
Request the issuer to perform a challenge as follows:
- Post the
creq
value to theacsUrl
URL (the Issuer Authentication URL) as shown in the example below (case-sensitive!):
(Thecreq
andacsUrl
fields were received in thepaymentOption.card.threeD
block in the previous payment (or authorize3d) response step.)Example Challenge – Posting the
creq
value in theacsUrl
URL-
<form method="POST" action="https://3dsn.sandbox.nuvei.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmljYXRpb25VUkwiOiJodHRwczovLzNkc2VjdXJlc2FmZWNoYXJnZS4wMDB3ZWJob3N0YXBwLmNvbS8zRHYyL25vdGlmaWNhdGlvblVybC5waHAiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjE0MDI2NzdmLWI5NjUtNDQ5Zi1hNzVkLTdhNDBjMGNkZjhhMyIsImFjc1RyYW5zSUQiOiI1NGU1ZWU1Ny1iMDJmLTQ5MzItYjNlMy1mNTk3ZGZlYTdkMjQiLCJkc1RyYW5zSUQiOiJiNzFhN2Q1ZC1jYzM4LTRjZTktODBjMy01MGE3ZDUzMjcxZjcifQ=="> creq:<input type="area" id="creq" name="creq" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjE0MDI2NzdmLWI5NjUtNDQ5Zi1hNzVkLTdhNDBjMGNkZjhhMyIsImFjc1RyYW5zSUQiOiI1NGU1ZWU1Ny1iMDJmLTQ5MzItYjNlMy1mNTk3ZGZlYTdkMjQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=" />; <input type="submit" value="proceed to issuer"> </form>
-
- The customer is redirected to the issuer’s challenge page and performs the challenge.
Upon completion of the challenge process, the issuer returns a base64-encodedCRes
response to thenotificationUrl
on your server:Example of the Encoded
CRes
Response Returned after the Challenge-
ewoidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLAoiYWNzVHJhbnNJRCI6ImQ3YzFlZTk5LTk0NzgtNDRhNi1iMWYyLTM5MWUyOWM2YjM0MCIsCiJtZXNzYWdlVHlwZSI6IkNSZXMiLAoibWVzc2FnZVZlcnNpb24iOiIyLjEuMCIsCiJ0cmFuc1N0YXR1cyI6IlkiLAoibWVzc2FnZUV4dGVuc2lvbiI6CiAgICBbewogICAgIm5hbWUiOiJtc2dleHRuYW1lIiwKICAgICJpZCI6IjUwMTM0MTU5MkJfMDAwMV80NTY4IiwKICAgICJjcml0aWNhbGl0eUluZGljYXRvciI6ZmFsc2UsCiAgICAiZGF0YSI6CiAgICAgICAgewogICAgICAgICJ2YWx1ZU9uZSI6Im1lc3NhZ2VleHRlbnNpb25kYXRhIiwKICAgICAgICAidmFsdWVUd28iOiJtb3JlbWVzc2FnZWV4dGVuc2lvbmRhdGEiCiAgICAgICAgfQogICAgfV0KfQ==
-
- Decode the base64-encoded
CRes
response.
Example of the Decoded
CRes
Response from the Challenge-
{ "threeDServerTransId":"8a880dc0-d2d2-4067-bcb1-b08d1690b26e", "acsTransId":"d7c1ee99-9478-44a6-b1f2-391e29c6b340", "messageType":"CRes", "messageVersion":"2.1.0", "transStatus":"Y", "messageExtension": [{ "name":"msgextname", "id":"501341592B_0001_4568", "criticalityIndicator":false, "data": { "valueOne":"messageextensiondata", "valueTwo":"moremessageextensiondata" } }] }
Parameter Description threeDSServerTransID
The 3DS server transaction ID, returned in the InitAuth3D
response.acsTransID
The ACS transaction ID, as generated by the issuer. messageExtension
Optional data necessary to support requirements not otherwise defined in 3D-Secure. messageType
The message type (CRes). messageVersion
The 3DS protocol version used for the authentication. transStatus
The transaction status. Possible values:
Y – challenge/authentication succeeded.
N – challenge/authentication failed.
-
- Continue to the next step:
- For a payment flow: Final Payment Request.
- For an authorize3d flow: Verify the 3D-Secure Authorization Result.
Parameter | Description |
---|
Parameter
|
Description
|
---|---|
PaReq (String) (Required) |
For the paReq field (note the capitalization), use the paymentOption.card.threeD.paRequest value, returned in the previous /payment (or /authorize3d) response step). |
TermUrl (String) (Required) |
The URL that the issuer should redirect your customer to, at the end of the 3D-Secure authentication process. |
MD (String) (Optional) |
Optional merchant data that can be posted back to the TermUrl at the end of the 3D-Secure authentication process. |
Parameter | Description |
---|
Parameter
|
Description
|
---|---|
threeDSServerTransId |
The 3DS server transaction ID, returned in the InitAuth3D response. |
acsTransId |
The ACS transaction ID, as generated by the issuer. |
messageExtension |
Optional data necessary to support requirements not otherwise defined in the 3D-Secure. |
messageType |
The message type (CRes). |
messageVersion |
The 3DS protocol version used for the authentication. |
transStatus |
The transaction status. Possible values: Y – challenge/authentication succeeded. N – challenge/authentication failed. |