3DS Server-to-Server

Home    Online Payments    REST 2.0 (Beta Version)    Features    Card Operations    3D-Secure    3DS Implementation    3DS Server-to-Server

On this page:

Overview

The Nuvei REST API 2.0 server-to-server 3D-Secure (3DS) card payment flow consists of:

  1. Rendering a Form – Collect the cardholder details on your payment page.
  2. Initial Payment Request – Send an initial REST 2.0 /payments request to determine whether the card supports 3DS; initialize the payment in the Nuvei system; and receive the fingerPrintingUrl and other details required for the 3DS fingerprinting.
  3. (Optional) 3DS Fingerprinting – Authenticates the client-side device.
  4. Second Payment Request – Send a /payments/{payment-id}/fingerprint request with fingerprintingIndicator.
    • If the card issuer approves the payment and accepts liability (frictionless) or declines the payment, the payment flow ends here.
    • If the card issuer requires a challenge, continue to the next step.
  5. 3DS Challenge – Authenticates the identity of the customer.
  6. Final Payment Request – If a 3DS challenge was performed, then send a liability-shift /payments/{payment-id}/challenge request with a challenge indicator and cRes.

If you are not using a 3DS flow, see REST 2.0 Non-3D-Secure.

3DS Card Payment Flow

1. Render a Payment Form

Render a form using the Nuvei APIs to collect the cardholder details on your payment page.

2. Initial Payment Request

To determine whether the credit card supports 3DS and what should be the next step in the process, send a POST /payments request with:

  • A header that includes includes the merchant’s API key for authentication. See the REST 2.0 Authentication page.
  • Either (not both):
    • paymentOption.card class with full card details, or
    • For a returning customer, a previously stored payment method:
      • buyerDetails.buyerId: “<unique customer identifier in merchant system>“
      • paymentOption.paymentToken.paymentTokenId: “<ID of a previously stored payment option>“
  • paymentOption.card.threeD containing mandatory fields:
    • fingerprintNotificationUrl:  “<URL to which the issuer should send the fingerprinting notification response>“
    • challengeNotificationUrl: “<URL to which the issuer should send a notification after the 3DS challenge step>” – This URL is needed for step 5. 3DS Challenge.
    • challengeWindowSize
  • Optional fields in the threeD class to increase the chances of receiving fingerprint status:
    • merchantUrl – 3DS Requestor URL, the fully qualified URL of the merchant’s website.
    • challenge.preference – The merchant’s challenge/exemption preference for each transaction sent to the issuer during the 3DS v2 decision stage.
      Possible values:
      • Challenge – You prefer that the issuer performs a challenge (even though this inconveniences your customer), and that the issuer ultimately accepts liability for the payment.
      • ExemptionRequest – You are willing to accept the risk (liability) for the payment. You do not want the issuer to perform a challenge.
      • NoPreference – This has the same effect as not sending the challenge.preference parameter.
  • buyerDetails class containing:
    • email
    • firstName
    • lastName
    • phone (if email is not provided)
    • buyerDetails.billingAddress class containing:
      • countryCode
      • address
      • zip
      • city
      • state
    • deviceDetails:
      • ipAddress
      • browser.screenHeight
      • browser.screenWidth
  • Only the fields listed above are mandatory in the buyerDetails and buyerDetails.billingAddress classes; however, providing the full buyerDetails.billingAddress and buyerDetails.shippingAddress classes increases the chances of frictionless authentication.
  • Nuvei strongly recommends not using the optional challenge.preference parameter for each transaction. Instead, Nuvei strongly recommends using the Nuvei Risk Engine, which is configured with challenge preferences for the merchant’s account.
    The Risk Engine makes the risk decision based on proven industry best practices, customized to your own challenge preferences.
    To enable the Risk Engine in your merchant account and configure your challenge preferences, contact our Risk Team.
Example /payments Request with 3DS Class
{
  "processingEntityId": "<your processingEntityid>",
  "transactionType": "Sale",
  "amount": 60,
  "currency": "USD",
  "paymentOption": {
    "card": {
      "cardHolderName": "John Smith",
      "cardNumber": "5101081046006034",
      "expirationMonth": "10",
      "expirationYear": "2026",
      "cvv": "345",
      "threeD": {
        "continueWithoutLiabilityShift": false,
        "fingerprintNotificationUrl": "<fingerprint notification URL>",
        "challengeNotificationUrl": "<challenge notification URL>",
        "challengeWindowSize": "01",
        "platformType": "02"
      }
    }
  },
  "buyerDetails": {
    "buyerId": "<unique customer identifier in your system>"
  },
  "deviceDetails": {
    "browser": {
      "acceptHeader": "Y",
      "colorDepth": 48,
      "javaEnabled": true,
      "javaScriptEnabled": true,
      "language": "en",
      "screenHeight": 1024,
      "screenWidth": 678,
      "timeZone": "+3",
      "userAgent": "Mozilla"
    }
  }
}
Example /payments Response with 3DS Class and Fingerprint Status
{
  "paymentId": "b5fcbdbf042b406fb2a8db677c579c2f",
  "transactionId": "7110000000004165594",
  "amount": 60,
  "currency": "USD",
  "transactionType": "InitAuth3D",
  "result": {
    "status": "fingerprint"
  },
  "partialApproval": {
    "requestedAmount": 60,
    "requestedCurrency": "USD"
  },
  "paymentOption": {
    "card": {
      "cardHolderName": "John Smith",
      "maskedCardNumber": "5****6034",
      "bin": "554506",
      "last4Digits": "6034",
      "expirationMonth": "10",
      "expirationYear": "26",
      "acquirerId": "19",
      "cardType": "Credit",
      "cardBrand": "MASTERCARD",
      "paymentTokenId": "80e768809ff94f8b9541d9d350a04130",
      "threeD": {
        "fingerprintUrl": "https://3dsn.sandbox.safecharge.com/ThreeDSMethod/api/ThreeDSMethod/threeDSMethodURL/",
        "fingerprintPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjkzYzE2MDhjLWM1YzMtNDVlYy05MmQ1LTdiMzVkNzE2MzNiMiIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuZmluZ2VyUHJpbnQ3ODM4NjQuY29tIn0",
        "version": "2.1.0",
        "challengePreferenceReason": "NoPreference",
        "acquirerDecision": "ExemptionRequest"
      }
    }
  }
}

Handling the Response

The result.status determines how or whether to proceed:

  • approved – Payment is approved. In case of cascading the payment as non-3DS, the response does not include the threeD class.

    The process ends here.

  • declined – Card issuer declined the payment. Do not proceed with transaction.

    The process ends here.

  • fingerprint – Fingerprinting should be performed. Continue with 3. Fingerprinting.
  • error – An error occurred.

    The process ends here.

For more information about REST 2.0 3DS responses, see 3DS Responses.

3. Fingerprinting (Optional)

3DS Fingerprinting for Web Browsers is an optional authentication step for 3D-Secure v2 (3DS2).

Prerequisites: In the previous step (2. Initial Payment Request):

  • The fingerprintNotificationUrl must have been included in the /payments request.
  • The fingerprintUrl and fingerprintPayload parameters should have been returned in the /payments response.

Follow the steps described in REST 2.0 3DS Fingerprinting.

4. Second Payment Request

If  result.status = “fingerprint” appears in the response to the initial /payments request, send a /payments/{payment-id}/fingerprint request with:

  • paymentId from the response to the initial /payments request.
  • processingEntityId
  • fingerprintingIndicator – Possible values:
    • Y – Merchant performed fingerprinting.
    • N – Merchant did not perform fingerprinting.
    • U – Merchant did not perform fingerprinting due to technical reasons.
Example /payments/{payment-id}/fingerprint Request
{
  "processingEntityId": "<your processingEntityId >",
  "fingerprintingIndicator": "Y"
}
Example /payments/{payment-id}/fingerprint Response – Frictionless Flow
{
  "paymentId": "aa039723f1ed4da2a1d5e4b723bb323c",
  "transactionId": "711000000028033669",
  "amount": 60,
  "currency": "USD",
  "transactionType": "Sale",
  "result": {
    "status": "approved"
  },
  "authCode": "111844",  
  "partialApproval": {
    "requestedAmount": 60,
    "requestedCurrency": "USD"
  },
  "paymentOption": {
    "card": {
      "cardHolderName": "John Smith",
      "maskedCardNumber": "5****6034",
      "bin": "400002",
      "last4Digits": "6034",
      "expirationMonth": "10",
      "expirationYear": "26",
      "acquirerId": "19",
      "cardType": "Credit",
      "cardBrand": "MASTERCARD",
      "paymentTokenId": "b4274bb4-7bb7-4658-ab92-ccec34618cc0",
      "threeD": {
        "version": "2.1.0",
        "eci": "5",
        "cavv": "AAQ2M0M5MEM5QzIzMkRFMUQ2NkQ=",
        "authenticationType": "02",
        "authenticationResult": "Y",
        "flow": "frictionless",
        "acsTransID": "b8301e4e-2e5b-4feb-a6f8-a768f1392ef4",
        "dsTransID": "7b1d3977-a2c0-45ec-9c23-ea47057a23ae",
        "challengePreferenceReason": "NoPreference",
        "acquirerDecision": "ExemptionRequest",
        "isLiabilityOnIssuer": "true"
      }
    }
  }
}
Example /payments/{payment-id}/fingerprint Response – status: “challenge”
{
  "paymentId": "b8c0cbd8edfd48ad94b3c32f79cc8dc4",
  "transactionId": "711000000028033669",
  "amount": 100,
  "currency": "USD",
  "transactionType": "Auth3D",
  "result": {
    "status": "challenge"
  },
  "partialApproval": {
    "requestedAmount": 100,
    "requestedCurrency": "USD"
  },
  "paymentOption": {
    "card": {
      "cardHolderName": "John Smith",
      "maskedCardNumber": "5****6034",
      "bin": "400002",
      "last4Digits": "6034",
      "expirationMonth": "10",
      "expirationYear": "26",
      "acquirerId": "19",
      "cardType": "Credit",
      "cardBrand": "VISA",
      "paymentTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "threeD": {
        "version": "2.1.0",
        "eci": "7",
        "acsUrl": "https://3dsn.sandbox.safecharge.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmljYXRpb25VUkwiOiJodHRwczovL2RvY3MubnV2ZWkuY29tLzNEc2ltdWxhdG9yL25vdGlmaWNhdGlvblVybC5waHAiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjJjYWE4NTU5LTcyNjktNDg3Ni05MTgxLTQwNjUyYjY2OTdlMCIsImFjc1RyYW5zSUQiOiIzYzVkZTY2Yi0zMzc3LTQ3OTgtOTQyMC01Yjc0YzNmMWE3MjQiLCJkc1RyYW5zSUQiOiI3NjU1NTgzMy05NTk5LTQ1MjAtYjBmYS1iNzg1ZjBkM2QzZmYiLCJkYXRhIjpudWxsLCJNZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
        "authenticationType": "01",
        "authenticationResult": "C",
        "acsChallengeMandate": "Y",
        "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjJjYWE4NTU5LTcyNjktNDg3Ni05MTgxLTQwNjUyYjY2OTdlMCIsImFjc1RyYW5zSUQiOiIzYzVkZTY2Yi0zMzc3LTQ3OTgtOTQyMC01Yjc0YzNmMWE3MjQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0",
        "flow": "Challenge",
        "acsTransID": "ed7b1ab1-3d9c-4073-9a83-82805d84b474",
        "dsTransID": "852e23af-6446-4abb-9693-bde0ac2c5bb5",
        "challengePreferenceReason": "NoPreference",
        "acquirerDecision": "ExemptionRequest"
      }
    }
  }
}

Handling the Response

The result.status determines how or whether to proceed:

  • challenge – Perform a 3DS Challenge.
  • approved – Payment was approved. The frictionless payment was made due to one of the following:
    • A cavv value is returned, the eci* value is either 5 (Visa) or 2 (Mastercard), and the issuer accepts liability (liability shift).
      *The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3DS program.

      The process ends here.

    • If the merchant requested a 3DS Exemption, the issuer approved a non-3DS transaction. The issuer does not accept liability (no liability shift).

      The process ends here.

  • declined – The card issuer declined the payment. Do not proceed with transaction.
    The response also includes:
    • eci is negative and the response does not include cavv.
    • A code and reason.

      The process ends here.

  • error – An error occurred. The 3DS authentication failed.

The process can end here. However, subject to risk considerations, the merchant might still want to proceed with a REST 2.0 Non-3DS (without liability shift) payment transaction. Simply submit a /payments request without the threeD class.

For more information about REST 2.0 3DS responses, see 3DS Responses.

5. 3DS Challenge

For instructions on implementing the authentication challenge, see REST 2.0 3DS Authentication Challenge.

6. Final Payment Request

This step handles the response from the 3DS challenge.

For a description of the 3DS authentication response returned by the issuer, see REST 2.0 3DS Responses, which also describes the relevant 3DS challenge or exemption with REST 2.0 Challenge Preference Reasons.

Perform the next relevant step depending on the outcome of the 3DS challenge:

  • If the customer did not complete the challenge successfully, then the process ends here.
    For 3DS2 – Decoded CRes contains transStatus: “N“.
  • If the customer completed the challenge successfully, then:
    For 3DS2 – Decoded CRes contains transStatus: “Y“.
    Complete the payment process by sending a final Liability Shift Payment (3DS2) request (see below).

Liability Shift – 3DS2

If the 3DS Challenge was successful, then complete the payment process by sending a /payments/{payment-id}/challenge  request with:

  • paymentId from the response to the initial /payments request.
  • processingEntityId
  • cRes
Example Liability Shift /payments/{payment-id}/challenge Request
{
  "processingEntityId": "<your processingEntityid>",
  "cRes": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImJkZGU1MjhhLTAxNWMtNDM1ZS04MTNkLTFkNmU1NzU2Zjk5ZiIsImFjc1RyYW5zSUQiOiI3MjEzZGFmOC00MWNhLTQ1NmEtOTQxOC1iOGZkMTNlYTFiNjUiLCJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidHJhbnNTdGF0dXMiOiJZIiwibWVzc2FnZUV4dGVuc2lvbiI6W3sibmFtZSI6Im1zZ2V4dG5hbWUiLCJpZCI6IjUwMTM0MTU5MkJfMDAwMV80NTY4IiwiY3JpdGljYWxpdHlJbmRpY2F0b3IiOmZhbHNlLCJkYXRhIjp7InZhbHVlT25lIjoibWVzc2FnZWV4dGVuc2lvbmRhdGEiLCJ2YWx1ZVR3byI6Im1vcmVtZXNzYWdlZXh0ZW5zaW9uZGF0YSJ9fV0sImFjc1NpZ25lZENvbnRlbnQiOm51bGx9"
}
 Example Liability Shift /payments/{payment-id}/challenge Response
{
  "paymentId": "b8c0cbd8edfd48ad94b3c32f79cc8dc4",
  "transactionId": "711000000028034738",
  "amount": 100,
  "currency": "USD",
  "transactionType": "Sale",
  "result": {
    "status": "approved"
  },
  "authCode": "111818",  
  "partialApproval": {
    "requestedAmount": 100,
    "requestedCurrency": "USD"
  },
  "paymentOption": {
    "card": {
      "cardHolderName": "John Smith",
      "maskedCardNumber": "5****6034",
      "bin": "400002",
      "last4Digits": "6034",
      "expirationMonth": "10",
      "expirationYear": "26",
      "acquirerId": "19",
      "cardType": "Credit",
      "cardBrand": "MASTERCARD",
      "paymentTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "merchantReference": "12391284AF87C7D2",
      "threeD": {
        "version": "2.1.0",
        "eci": "5",
        "cavv": "czFkVjllVGtFNHJsUzlNd3ZQVjQ=",
        "whiteListStatus": "N",
        "acsChallengeMandate": "Y",
        "authenticationType": "01",
        "authenticationResult": "Y",
        "flow": "Challenge",
        "dsTransID": "852e23af-6446-4abb-9693-bde0ac2c5bb5",
        "challengePreferenceReason": "NoPreference",
        "acquirerDecision": "ExemptionRequest",
        "isLiabilityOnIssuer": "true"
      }
    }
  }
}

For more information about REST 2.0 3DS responses, see 3DS Responses.

Last update iconLast modified November 2024