• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
  • Accept Payment
    • Checkout Page
      • Quick Start for Checkout
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start for Web SDK
      • Nuvei Fields
      • Nuvei Fields Stylizing
      • APMs for Web SDK
      • Web SDK Additional Functions
      • Web SDK FAQs
    • Checkout SDK
      • Checkout SDK Payment Form - UI Styling
    • Server-to-Server
    • Plugins
    • Mobile SDKs
      • Android Mobile SDK
      • iOS Mobile SDK
    • Payment Scenarios
    • Flow Diagrams
  • Features
    • API Authentication and the Session Token
    • PCI and Tokenization
    • 3D-Secure
    • Card-on-File
    • Merchant-Initiated Transactions (MIT)
    • Alternative Payment Methods (APMs)
    • Refund
    • Void
    • Auth, PreAuth, Sale and Settle
    • Direct Merchant Notifications (DMNs)
    • Subscription (Rebilling)
    • Zero-Authorization
    • Partial Approval
    • Marketplaces
  • Guides
    • Plugins
      • Magento 1
      • Magento 2
      • WooCommerce
      • PrestaShop
      • Open Cart
      • Shopify (via AsiaBill)
      • Mirakl
    • Choosing an Integration Method
    • Testing Cards, APIs and APMs
      • Testing Cards
      • Testing APMs
      • Testing APIs with Postman
      • Web SDK Scenarios
    • Response Handling and Errors
      • Error Handling
      • Error Codes
    • Country and Currency Codes
    • Direct Merchant Notifications (DMNs)
    • 3D-Secure
      • 3D-Secure Explained
      • 3D-Secure How-To Guide
      • 3D-Secure MPI-Only for Web SDK
      • 3D-Secure MPI-Only for Server-to-Server
      • 3D-Secure Fingerprinting
      • 3D-Secure Authentication Challenge
      • External MPI (Third-Party 3D-Secure)
      • 3D-Secure Response Values
    • Alternative Payments Guide
      • APM Input Fields
      • APM subMethod Classes
      • APM Supported Countries and Currencies
    • Apple Pay
      • Register in the Apple System
        • Create an Apple ID
        • Enroll in the Apple Developer Program
          • Submit an Enrollment Request
          • Complete the Enrollment Process
          • Activate your Apple Developer Program Account
        • Register a Merchant ID in the Apple System
          • Create a Merchant ID
          • Create a Payment Processing Certificate
          • Create a Merchant Identity Certificate
          • Register and Verify your Domain
      • Apple Pay Integration
        • Nuvei Apple Pay Integration Solutions
          • Nuvei Checkout Page IFrame Solution – Main Solution for Cashier
          • Static Apple Pay Button Solution on Merchant Site
          • Dynamic Apple Pay Button Solution on Merchant Site
        • Apple Pay Integration Testing
    • Payment Facilitators (PayFac)
    • Cashier
      • Cashier Events Guide
    • Withdrawal Guide
    • Risk Guide
    • eKYC Guide
    • Server SDKs
      • Java SDK
      • .NET SDK
      • PHP SDK
      • Node.JS SDK
    • Fast Track Onboarding Developer Guide
    • Currency Conversion Services
      • Multiple Currency Pricing (MCP)
        • Accepting Payment for a Sale using MCP Values
      • Dynamic Currency Conversion (DCC)
        • DCC in Cashier or Checkout Page
        • DCC in REST API Workflows
        • DCC in Web SDK Workflows
  • Additional Links
    • FAQs
    • API Reference
    • Release Notes

Web SDK Additional Functions

Contents
  • Overview
  • 3D-Secure-Only Request (without payment) – authenticate3d()
  • Web SDK (without Nuvei Fields) – createPayment()
  • Authorization-Only – openOrder
    • Auth and Settle
    • Zero-Authorization
  • Tokenization-Only
    • Overview
    • Step 1: Authenticate the Merchant
    • Step 2. Perform Tokenization-only using the Web SDK
    • Step 3. Submit a Payment (Non-3D)
  • Existing User (with no cardholder data collection)
  • Existing User, Collecting only CVV

Overview

This section discusses additional functions that you can perform with Nuvei Web SDKs.

Refer to the Web SDK Scenarios section which contains live Web SDK examples, which you can view and modify to test your code, using JSFiddle.

3D-Secure-Only Request (without payment) – authenticate3d()

You can use the Web SDK to perform a 3D-Secure-Only request, where Nuvei only authorizes and authenticates your customer, but does not process the payment.

Invoke this 3D-Secure-Only service by sending an authenticate3d() request. The input parameters for this method are identical to the createPayment() method, but instead of performing a payment, the method returns a 3D-Secure response which includes these authentication values:

  • eci – Upon successful authentication, the eci value is either 5 (Visa) or 2 (Mastercard).
  • cavv – Upon successful authentication, this will contain the encrypted authentication value, otherwise it will be either empty or null.

authenticate3d() can work with or without Nuvei Fields, tokenization, etc.

Example authenticate3d() Request
// Instantiate Nuvei API 
var sfc = SafeCharge({ 
    env: 'test', // the environment you are running on, 'prod' for production 
    merchantId: '<your merchantId>', // your Merchant ID provided by Nuvei 
    merchantSiteId: '<your merchantSiteId>' // your Merchant site ID provided by Nuvei 
  });

function main(){
sfc.authenticate3d({
    "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0", //as received from openOrder
    "clientUniqueId": "695701003",
    "paymentOption": {
      "card": {
        "cardNumber": "5333302221254276",
        "cardHolderName": "john smith",
        "expirationMonth": "12",
        "expirationYear": "25",
        "CVV": "217"
      }
    },    "billingAddress": {
      "email": "someone@somedomain.com",
      "country": "GB"
    }
  }, function(result) {
    console.log(result.cavv)
  });
}

Web SDK (without Nuvei Fields) – createPayment()

If you would rather not use Nuvei Fields, you can provide the cardholder information directly and charge your customer using the createPayment() method, as shown in the example below.

This is not recommended. There are no benefits to not using Nuvei Fields for cardholder information collection.
However, if you decide to collect the cardholder information on your own, then you will need to complete the PCI SAQ A -EP form, and commit to various extra security measures. You will also need to hire an authorized third-party company to perform quarterly scans.

Example createPayment() Request
// Instantiate Nuvei API 
var sfc = SafeCharge({ 
    env: 'test', // the environment you are running on, 'prod' for production 
    merchantId: '<your merchantId>', // your Merchant ID provided by Nuvei 
    merchantSiteId: '<your merchantSiteId>' // your Merchant site ID provided by Nuvei 
  });

function main() {
  sfc.createPayment({
    "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0", //as received from openOrder
    "clientUniqueId": "695701003", // optional
    "paymentOption": {
      "card": {
        "cardNumber": "5333302221254276",
        "cardHolderName": "john smith",
        "expirationMonth": "12",
        "expirationYear": "25",
        "CVV": "217"
      }
    },
    "billingAddress": {
      "email": "someone@somedomain.com",
      "country": "GB"
    }
  }, function(res) {
    console.log(res)
  });
}

Authorization-Only – openOrder

As explained previously, the Web SDK seamlessly guides you throughout the payment process, covering both PCI and 3D-Secure processes. However, some merchants prefer an authorization-only request.

There are two ways to perform authorization-only requests with Web SDK:

  • Auth and Settle
    • Authorize, and Settle the amount at later stage.

      For full details, see the Auth and Settle section.

  • Zero-Authorization
    • Authorize a zero amount.

      For full details, see the Zero-Authorization section.

      This is used to verify a card or add a card to your customer’s account for future use.
      Perform a zero amount transaction as follows:
      1. Call the /openOrder method and set amount=0 and transactionType=Auth.
        Example openOrder Request
        {
            "merchantId": "<your merchantId>",
            "merchantSiteId": "<your merchantSiteId>",
            "userTokenId": "487106",
            "clientUniqueId": "12345",
            "clientRequestId": "1484759782197",
            "currency": "USD",
            "transactionType": "Auth",
            "amount": "0",
            "timeStamp": "20170118191751 ",
            "checksum": "6b53666fc048a825be63cbb820da467b"
        }
      2. From your client-side, call a createPayment() or an authenticate3d() request. Use the sessionToken returned from the /openOrder, and set the amount field to zero, as described in the Quick Start section.

Tokenization-Only

Overview

This section describes how to implement a tokenization-only flow.

Who uses the Tokenization-only Flow

The tokenization-only integration is suited to merchants who:

  • Want to be descoped from PCI, but still be in control of the complete flow from their server-side.
  • Perform complete 3D-Secure flows, both server-side and client-side.
  • Want to be able to choose either 3D-Secure V1 or V2 flows, in frictionless or challenge mode.

Implementing a full 3D-Secure flow requires a high level of understanding of the 3D-Secure process and of the card schemes mandate. Using the tokenization-only request is not recommended, unless you are familiar with these procedures. For a simpler integration experience, consider using the 3D-Secure MPI-Only for Web SDK integration.

Tokenization-only Flow Integration Steps

  • Step 1. Authenticate the Merchant – Sets up an order in the Nuvei system.
  • Step 2. Perform Tokenization-only using the Web SDK – Perform Tokenization-only using the Nuvei Web SDK getToken() method.
  • Step 3. Submit a Payment (Non-3D) – Submit a /payment API request using the Nuvei client-side Web SDK.

Step 1: Authenticate the Merchant

Generate a sessionToken by posting a /getSessionToken API server-side call, and include the checksum field.

Calculate the checksum value as follows:

  1. Concatenate the following fields, in this order, with no spaces, and no separators between the fields:
    merchantId, merchantSiteId, clientRequestId, timeStamp,  {your secret key}
  2. Calculate the SHA256 hash of the concatenated fields.
Example /getSessionToken Request
{
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId": "<The ID of the API request in the merchant’s system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}
Example /getSessionToken Response

The response returns the sessionToken which you will need for authentication in all subsequent calls in the flow.

{
    "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0",
    "internalRequestId": 188635168,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "479748173730597238",
    "merchantSiteId": "180083",
    "version": "1.0",
    "clientRequestId": "20200510165419"
}

Step 2. Perform Tokenization-only using the Web SDK

Perform Tokenization-only using the Nuvei Web SDK getToken() method which tokenizes the card and cvv, and returns the ccTempToken.
You can then use the ccTempToken to process the payment using the /payment API method.

Example of getToken() Request
var sfc = SafeCharge({
    env: 'int', // the environment you are running on (if omitted, default is 'prod')
    merchantId: '<your merchantId>', // your Merchant ID provided by Nuvei
    merchantSiteId: '<your merchantSiteId>' // your Merchant site ID provided by Nuvei
  });

  var ScFields = sfc.fields({
    fonts: [{
        cssUrl: 'https://fonts.googleapis.com/css?family=Source+Code+Pro'
      }, // include your custom fonts
    ],
    locale: 'en' // you can set your users preferred locale, if not provided we will try to autodetect
  });

  var style = {
    base: {
      fontFamily: 'Roboto, sans-serif',
      color: "#045d47",
      fontSmoothing: 'antialiased',
      '::placeholder': {
        color: '#ccb654'
      }
    },
    invalid: {
      color: '#e5312b',
      ':focus': {
        color: '#303238'
      }
    },
    empty: {
      color: '#BADA55',
      '::placeholder': {
        color: '#cc3ac2'
      }
    },
    valid: {
      color: '#2b8f22'
    }
  };

  var scard = ScFields.create('card', {
    style: style
  });
  scard.attach(document.getElementById('card-field-placeholder'));  
  
  function main() {
    sfc.getToken(scard).then(function(result) {
      if (result.status === 'SUCCESS') {
        console.log(result.paymentOption.ccTempToken) // pass the paymentOption block, as is, to the payment API call
      } else {
        // handle error.
      }
    });
  }

Step 3. Submit a Payment (Non-3D)

You can submit a /payment API request (3D-Secure or Non-3D Secure) using the Nuvei client-side Web SDK, using the ccTempToken returned by the getToken() method.

This example shows a Non-3D Secure payment.

Example /payment Request (Non-3D)
{ 
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"<your merchantId>",
   "merchantSiteId":"<your merchantSiteId>",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"487106",
   "clientUniqueId":"12345",
   "paymentOption":{ 
      "card":{ 
         "ccTempToken":"c0275892-fce1-488f-9268-1c826b2574e8"
      }
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
   "timeStamp":"20191105081132",
   "checksum":"5582d0189dd440f4bbf960569ec22e77"
}

Existing User (with no cardholder data collection)

Many merchants keep accounts for their users (customers), and would like to charge them on multiple occasions. Using the Nuvei Tokenization solution, customer cardholder information only needs to be collected once, and becomes available for use in future payments from then on.

Collecting cardholder information – Calling the Web SDK’s createPayment() or authenticate3d() methods returns a userPaymentOptionId, representing the customer’s full cardholder information collected during that transaction. From then on, you can allow a returning customer to select any of their previously stored payment methods for their current payment.

Retrieving stored cardholder information – To retrieve the userPaymentOptionId initially, you need to specify the userTokenId field when calling the createPayment() or authenticate3d() functions. These fields identify the customer and guarantee that the payment method (card) being used indeed belongs to that customer. You need to specify the fields both on the initial call, as well as on subsequent calls.

Since you do not collect any cardholder information, there is no need to use Nuvei Fields.

Handling card expiration – Store card expiration details together with the userPaymentOptionId. To set a new expiration date, send a createPayment() call, as shown in the example below.

Example createPayment Request
var sfc = SafeCharge({
    env: 'int', // the environment you are running on (if omitted, default is 'prod')
    merchantId: '<your merchantId>', // your Merchant ID provided by Nuvei
    merchantSiteId: '<your merchantSiteId>' // your Merchant site ID provided by Nuvei
  });

  function main() {
    sfc.createPayment({
      "sessionToken": '7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0', //as received from the openOrder
      "userTokenId": "487106",
      "clientUniqueId": "695701003", // optional
      "paymentOption": {
        "userPaymentOptionId": "53622598",
        "card": {
          "expirationMonth": "12", //optional - sets a new expiration date
          "expirationYear": "26", //optional
          "CVV": "217"
        }
      },
      "billingAddress": {
        "email": "someone@somedomain.com",
        "country": "GB"
      }
    }, function(res) {
      console.log(res);
   });
}

Existing User, Collecting only CVV

As explained in the previous section, the Web SDK can process tokenized cardholder information using only the userPaymentOptionId field.

Authenticating payments with the CVV/CVC verification codes – To authenticate a payment with the CVV/CVC verification codes, send a createPayment() or authenticate3d() request to collect the CVV from Nuvei Fields.

Most merchants do not authenticate a payment with the CVV/CVC verification codes. Merchants operating in high-risk industries, such as gambling, are typically required by industry regulation, to authenticate in this way. If you do not belong to such an industry, simply follow the standard way of charging your existing customers, as described in the previous section.

Handling card expiration – Store card expiration details together with the userPaymentOptionId. To set a new expiration date, send a createPayment() call, as shown in the example below.

Example createPayment Request – without Nuvei Fields
var sfc = SafeCharge({
    env: 'int', // the environment you are running on (if omitted, default is 'prod')
    merchantId: '<your merchantId>', // your Merchant ID provided by Nuvei
    merchantSiteId: '<your merchantSiteId>' // your Merchant site ID provided by Nuvei
  });

  function main() {
    sfc.createPayment({
      "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0", //as received from the openOrder
      "userTokenId": "487106",
      "clientUniqueId": "695701003", // optional
      "paymentOption": {
        "userPaymentOptionId": "53622598",
        "card": {
          "expirationMonth": "12", //optional - sets a new expiration date
          "expirationYear": "26",  //optional 
          "CVV": "112"        
         }
      },
      "billingAddress": {
        "email": "someone@somedomain.com",
        "country": "GB"
      }
    }, function(res) {
      console.log(res);
   });
}
Example createPayment Request – with Nuvei Fields
var sfc = SafeCharge({
  env: 'int', // the environment you are running  on ('prod' for production)
  merchantId: '<your merchantId>', // your Merchant ID provided by Nuvei
  merchantSiteId: '<your merchantSiteId>' // your Merchant site ID provided by Nuvei
});

var ScFields = sfc.fields({
  fonts: [{
      cssUrl: 'https://fonts.googleapis.com/css?family=Roboto'
    }, // include your custom fonts
  ]
});

var ScFieldStyles = {
  base: {
    color: '#32325D',
    fontWeight: 500,
    fontFamily: 'Roboto, Consolas, Menlo, monospace',
    fontSize: '16px',
    fontSmoothing: 'antialiased',
    '::placeholder': {
      color: '#CFD7DF',
    },
    ':-webkit-autofill': {
      color: '#e39f48',
    },
  },
  invalid: {
    color: '#E25950',
    '::placeholder': {
      color: '#FFCCA5',
    },
  },
};

var ScFieldClasses = {
  focus: 'focused',
  empty: 'empty',
  invalid: 'invalid',
  complete: 'complete',
};

var cardCvc = ScFields.create('ccCvc', {
  style: ScFieldStyles,
  classes: ScFieldClasses
});
cardCvc.attach('#card-cvc');

function main() {
  sfc.createPayment({
    "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0", //as received from the openOrder
    "userTokenId": "487106",
    "paymentOption": {
      "userPaymentOptionId": "13084323",
      card: {
       "expirationMonth": "12",  // optional - sets a new expiration date
       "expirationYear": "2026", // optional
       "CVV": cardCvc
      }
    }
  }, function(result) {
    console.log(result);
  })
}

DCC in Web SDK

You can use DCC in Web SDK payment requests, by calling the clientGetDccDetails Web SDK method.

The Web SDK will retrieve DCC information based on the previously received payment method, source amount, source currency and target currency.

The output of this method will be the complete DCC information.

 

 

Invoke this by sending a clientGetDccDetails Web SDK request.

 

 

2021 Nuvei. All rights reserved.