3D-Secure Authentication Challenge

On this page:

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:

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)

Challenge for 3D-Secure v1

Request the issuer to perform a challenge as follows:

  1. Post the following form to the acsUrl URL (the Issuer Authentication URL) by concatenating the following HTTP GET fields (hidden input fields) onto the acsUrl 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>
      ParameterDescription
      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.
    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>
-->
  2. 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 the TermUrl (that you provided in the form above) and returns a base64-encoded PaRes field containing the 3D-Secure response data to the TermUrl.
    (You need the PaRes value in the next step to send the paResponse field.)
  3. Continue to the next step:

Challenge for 3D-Secure v2

Request the issuer to perform a challenge as follows:

  1. Post the creq value to the acsUrl URL (the Issuer Authentication URL) as shown in the example below (case-sensitive!):
    (The creq and acsUrl fields were received in the paymentOption.card.threeD block in the previous payment (or authorize3d) response step.)
    Example Challenge – Posting the creq value in the acsUrl 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>
  2. 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-encoded CRes response to the notificationUrl on your server:
    Example of the Encoded CRes Response Returned after the Challenge
    • ewoidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLAoiYWNzVHJhbnNJRCI6ImQ3YzFlZTk5LTk0NzgtNDRhNi1iMWYyLTM5MWUyOWM2YjM0MCIsCiJtZXNzYWdlVHlwZSI6IkNSZXMiLAoibWVzc2FnZVZlcnNpb24iOiIyLjEuMCIsCiJ0cmFuc1N0YXR1cyI6IlkiLAoibWVzc2FnZUV4dGVuc2lvbiI6CiAgICBbewogICAgIm5hbWUiOiJtc2dleHRuYW1lIiwKICAgICJpZCI6IjUwMTM0MTU5MkJfMDAwMV80NTY4IiwKICAgICJjcml0aWNhbGl0eUluZGljYXRvciI6ZmFsc2UsCiAgICAiZGF0YSI6CiAgICAgICAgewogICAgICAgICJ2YWx1ZU9uZSI6Im1lc3NhZ2VleHRlbnNpb25kYXRhIiwKICAgICAgICAidmFsdWVUd28iOiJtb3JlbWVzc2FnZWV4dGVuc2lvbmRhdGEiCiAgICAgICAgfQogICAgfV0KfQ==
  3. 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"
        }
    }]
}
      ParameterDescription
      threeDSServerTransIDThe 3DS server transaction ID, returned in the InitAuth3D response.
      acsTransIDThe ACS transaction ID, as generated by the issuer.
      messageExtensionOptional data necessary to support requirements not otherwise defined in 3D-Secure.
      messageTypeThe message type (CRes).
      messageVersionThe 3DS protocol version used for the authentication.
      transStatusThe transaction status. Possible values:
      Y – challenge/authentication succeeded.
      N – challenge/authentication failed.
  4. Continue to the next step:

 

Parameter Description

 

 

Parameter Description