• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Checkout Examples
      • Server-to-Server
      • Payment Scenarios
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Flow Diagrams
      • Plugins
        • Magento
          • Rebilling with Magento
        • WooCommerce
          • Rebilling with WooCommerce
        • PrestaShop
          • PrestaShop with Web SDK
          • PrestaShop with Checkout
        • OpenCart
        • Shopify (via AsiaBill)
        • Mirakl
        • Salesforce
        • SAP
        • WIX
      • Marketplaces
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion (DCC and MCP)
        • Payout
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscription (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
    • Guides
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APIs with Postman
        • Testing APMs
      • Response Handling
      • Alternative Payment Guides (APMs)
      • Airline Ticket Guides
        • Airline Addendum
        • External Authorization Addendum
      • Payment Facilitators (PayFac)
      • Cashier
        • Cashier Events Guide
        • Cashier Features
      • Withdrawal Guide
      • Risk Guide
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • Chargebacks
      • eKYC Guide
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
      • Fast Track Onboarding Developer Guide
      • Currency Conversion Guides
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Website Compliance Guides
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    3D-Secure Authentication Challenge

    On this page:
    • Overview
    • Determine the Version of 3D-Secure Challenge to Perform
    • Challenge for 3D-Secure v1
    • Challenge for 3D-Secure v2

    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)

    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:
      • 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:

    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:
      • 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.

     

    2022 Nuvei. All rights reserved.