Overview

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

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.

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.

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

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

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.

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.

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.

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);
  })
}