Web SDK Additional Functions

On this page:

Overview
Returning User – No Collection
Returning User – CVV
Authorization-Only
Zero-Authorization
Without Nuvei Fields
Tokenization-Only
3D-Secure
- 3D-Secure Authentication Only
Currency Conversion
- MCP for Web SDK
- DCC for Web SDK
APM
- APM Recurring Billing
- Customer Registration via APM
Apple Pay Web SDK Integrations
Features
- Blocking Cards
Methods
- Get Card Details

Overview

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

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

Returning User – No 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() methods. 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', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
    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);
   });
}

Returning User – 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. However, 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', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
    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', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
  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);
  })
}

Authorization-Only

You can send an authorization request to ensure that the customer’s selected payment method (card) account has sufficient funds to settle the payment.

An authorization applies a temporary lock on funds in a customer’s selected payment method (card) account for a limited timeframe equal to the value of the purchase amount.

The authorization must be followed by one or more settle requests to complete the purchase or by a void to cancel the temporarily lock.

For full details, see the Authorization section.

There is another way to perform an authorization-only request using a Zero-Authorization request, as described below.

Zero-Authorization

You can perform an authorization-only request to verify a card or add a card to your customer’s account for future use by simply sending a “zero” amount transaction.

Perform a zero amount transaction as follows:

First send an /openOrder request and set amount=0 and transactionType=Auth.

Example `/openOrder` Request

{  
    "merchantId":"<your merchantId goes here>",
    "merchantSiteId":"<your merchantSiteId goes here>",
    "clientUniqueId":"<unique transaction ID in merchant's system>",
    "clientRequestId":"<unique request ID in merchant’s system>",
    "currency":"USD",
    "amount":"0",
    "userTokenId": "<a user identifier>",
    "transactionType": "Auth",
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}

<?php
$safecharge = new \SafeCharge\Api\RestClient([
'environment' => \SafeCharge\Api\Environment::INT,
'merchantId' => '<your merchantId>',
'merchantSiteId' => '<your merchantSiteId>',
'merchantSecretKey' => '<your merchantSecretKey>',
]);

$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'clientUniqueId'    => '<unique transaction ID in merchant's system>',
    'clientRequestId'   => '<unique request ID in merchant’s system>',
    'currency'          => 'USD',
    'amount'            => '0',
    'userTokenId'       => '<a user identifier>',
    'transactionType' => 'Auth',
    'billingAddress' => [
        'country'   => "US",
        "email"     => "john.smith@email.com",
    ],
]);
?>

public static void main(String[] args) {
// for initialization 
String merchantId = "<your merchantId>";
String merchantSiteId = "<your merchantSiteId>";
String merchantKey = "<your merchantKey>";
safecharge.initialize(merchantId, merchantSiteId, merchantKey, Constants.HashAlgorithm.SHA256);

//for openOrder
String userTokenId = "<a user identifier>";
String clientUniqueId = "<unique transaction ID in merchant's system>";
String clientRequestId = "<unique request ID in merchant’s system>";
String currency = "USD";
String amount = "0";
String transactionType = "Auth";

UserAddress billingAddress = new UserAddress();
billingAddress.setEmail("john.smith@email.com");
billingAddress.setCountry("US");

Safecharge safecharge = new Safecharge();
SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId,
clientUniqueId, null, null, null, transactionType, currency, amount,
null, null, null, null, billingAddress, null, null, null,
null, null, null, null, null, null, null);
}

var safecharge = new Safecharge(
"<your merchantKey>",
"<your merchantId>",
"<your merchantSiteId>",
"<your server host value>",
HashAlgorithmType.SHA256
);
var response = safecharge.OpenOrder(
 "USD",
 "0",
 transactionType: "Auth",
 userTokenId: "<a user identifier>",
 clientUniqueId: "<unique transaction ID in merchant's system>",
 clientRequestId: "<unique request ID in merchant’s system>",
 billingAddress: new UserAddress
 {
     Email = "john.smith@email.com",
     Country = "US",
 }
);

const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
safecharge.paymentService.openOrder({
    'clientUniqueId'   : '<unique transaction ID in merchant's system>',
    'clientRequestId'  : '<unique request ID in merchant’s system>',
    'currency'         : 'USD',
    'amount'           : '0'
    'transactionType' : 'Auth',
    'userTokenId' : '230811147',
    'billingAddress': {
        'email': "john.smith@email.com",
        'country': "US"
    },
}, function (err, result) {
    console.log(err, result)
});

Then, from your client-side, use the sessionToken returned from the /openOrder to send a createPayment() or an authenticate3d() request. Set the amount=0 and transactionType=Auth as described in the Quick Start topic.

For full details, see the Zero-Authorization with Web SDK topic.

Without Nuvei Fields

You can provide the cardholder information directly and charge your customer using the createPayment() method without using Nuvei Fields, as shown in the example below.

It is recommended to use Nuvei Fields to collect cardholder details for your convenience.
However, if you decide to collect the cardholder information on your own, then you must complete the PCI SAQ A -EP form and commit to various extra security measures. You must also hire an authorized third-party company to perform quarterly scans.

Example `createPayment()` Request

// Instantiate Nuvei API 
var sfc = SafeCharge({ 
    env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted) 
    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)
  });
}

Tokenization-Only

The tokenization-only flow uses the Nuvei Web SDK getToken() method to tokenize a card and cvv. It returns a ccTempToken which can then be used to process the payment using the /payment API method.

The ccTempToken is a temporary one-time token which is valid only for that API session. It can be used to process payments with the Nuvei server-to-server API, and still be PCI descoped.

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 3D-Secure with the tokenization-only request is not recommended unless you are familiar with the 3D-Secure requirements. For a simpler integration experience, consider using the 3DS MPI-Only for Web SDK integration.

See the full integration in the Tokenization-Only using Web SDK topic.

3D-Secure

3D-Secure Authentication Only

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 contains the encrypted authentication value; otherwise, it is either empty or null.

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

Example `authenticate3d()` Request

// Instantiate Nuvei API 
var sfc = SafeCharge({ 
    env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted) 
    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": "22",
        "CVV": "217"
      }
    },    "billingAddress": {
      "email": "someone@somedomain.com",
      "country": "GB"
    }
  }, function(result) {
    console.log(result.cavv)
  });
}

Currency Conversion

MCP for Web SDK

Integrating DCC is relatively simple because the regular payment workflow remains unchanged with a few additional steps.

See the full integration in the MCP for Web SDK topic.

DCC for Web SDK

Integrating DCC is relatively simple because the regular payment workflow remains unchanged with a few additional steps.

See the full integration in the DCC for Web SDK topic.

APM

APM Recurring Billing

The subMethod class can be used in a createPayment() request method to access the APM Recurring Billing special APM feature.

The createPayment() example below shows:

An APM payment using the paymentMethod parameter to specify the "apmgw_expresscheckout" PayPal APM.
The optional subMethod parameter is used to specify the "ReferenceTransaction" flag, which indicates the “PayPal – Billing Agreement“, in an advanced APM Recurring billing flow.

Example `createPayment()` Request

sfc.createPayment({
  "sessionToken": "<sessiontoken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientUniqueId": "695701003",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_expresscheckout"
    },
    "subMethod": {
      "subMethod": "ReferenceTransaction"    // APM provider who supports the APM Recurring Billing feature
    }
  },
  "billingAddress": {
    "country": "GB",
    "email": "someone@somedomain.com"
  }
}, function(res) {
  console.log(res);
  if (res.cancelled === true) {
    example.querySelector('.token').innerText = 'cancelled';
  } else {
    example.querySelector('.token').innerText = res.transactionStatus + ' – Reference: ' + res.transactionId;
  }
  example.classList.add('submitted');
});

Customer Registration via APM

The subMethod class can be used in a createPayment() request method to access the Customer Registration via APM special APM feature.

The createPayment() example below shows:

An APM payment using the paymentMethod parameter to specify the "apmgw_expresscheckout" PayPal APM.
The optional subMethod parameter is used to specify the "QuickRegistration" flag, which indicates PayPal as the Customer Registration provider in an advanced Customer Registration via APM flow.

Example `createPayment()` Request

sfc.createPayment({
  "sessionToken": "<sessiontoken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientUniqueId": "695701003",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_expresscheckout"
    },
    "subMethod": "QuickRegistration"   // APM provider who supports the Customer Registration feature
  },
  "billingAddress": {
    "country": "GB",
    "email": "someone@somedomain.com"
  }
}, function(res) {
  console.log(res);
  if (res.cancelled === true) {
    example.querySelector('.token').innerText = 'cancelled';
  } else {
    example.querySelector('.token').innerText = res.transactionStatus + ' – Reference: ' + res.transactionId;
  }
  example.classList.add('submitted');
});

Apple Pay Web SDK Integrations

Nuvei offers the following Apple Pay Integration solutions using Web SDK to add the Apple Pay payment method to your websites or applications.

Static Apple Pay Button
Dynamic Apple Pay Button
Static Apple Pay Button using Web SDK

Static Apple Pay Button

This solution integrates an Apple Pay payment method button into Cashier or on your own Payment page.

See the full integration in the Static Apple Pay Button topic.

Dynamic Apple Pay Button

This solution integrates an Apple Pay payment method Button into your own payment page on your own site. Depending on user choices, the transaction total amount can be changed inside the Apple Pay payload collected in the Apple Pay overlay. (This is one of the main differences between the Static and the Dynamic JavaScript button solutions.)

For example, you can calculate the shipping price based on the billing address, or the shipping option selected, or the country/area for delivery, or taxes.

See the full integration in the Dynamic Apple Pay Button topic.

Static Apple Pay Button using Web SDK

This solution integrates an Apple Pay payment method Button into your own payment page using the Nuvei Web SDK.

See the full integration in the Static Apple Pay Button using Web SDK topic.

Features

Blocking Cards

You can block cards from being included in requests or being processed, as well as from being displayed to the customer in the Payment Methods list.

This can be done while initiating Web SDK when you create the SafeCharge() object.
Include the blockCards array parameter and specify the card types or collections to be blocked.
The blockCards array can contain the following card collections:

visa, mastercard, amex, diners, discover, jcb, dankort, unionpay
debit, credit
consumer, corporate

There is a “union” relationship between items in the array; therefore “all” cards in the specified collections are blocked.
For example, specifying: blockCards: ["amex","credit","corporate"] blocks all “amex” cards, and all “credit” type cards, and all “corporate” type cards.

Example `SafeCharge()` Function Specifying a `blockCards` Array

sfc = SafeCharge({
  env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted) 
  merchantId: '<your merchantId>', 
  merchantSiteId: '<your merchantSiteId>', 
  blockCards: ['amex', 'credit', 'consumer'] // block all amex cards and all credit cards and all consumer cards
});

All subsequent requests using this object block the specified cards, for example the createPayment() and authenticate3d() requests.

Methods

Get Card Details

You can use the getCardDetails() Web SDK method to retrieve all available details for a cardNumber or BIN number (the first 6 digits, which represent the issuer).

Example `getCardDetails()` Request

sfc.getCardDetails({
    sessionToken: "<sessiontoken>",  // as returned from getSessionToken result
    merchantId: "<your merchantId>", 
    merchantSiteId: "<your merchantSiteId>",
    cardNumber: "<cardNumber>",  // either Nuvei fields reference or card number or a BIN number
    clientRequestId: "<unique request ID in merchant’s system>",
    clientUniqueId: "<unique transaction ID in merchant's system>"
}, function(cardDetails) {
    console.log(cardDetails);
})

Example `getCardDetails()` Response

{
  "brand": "VISA",
  "cardType": "Credit",
  "program": "Visa Platinum",
  "visaDirectSupport": "0",
  "issuerCountry": "pe",
  "currency": "pen",
  "dccAllowed": false,
  "sessionToken": "eaeed493-6ed1-4e44-9cc9-7e698efe51e2",
  "internalRequestId": 212986558,
  "status": "SUCCESS",
  "reason": "",
  "errCode": 0,
  "merchantId": "479748173730597238",
  "merchantSiteId": "204388",
  "version": "1.0",
  "clientRequestId": "20201025110518"
}

Overview

Returning User – No Collection

Example createPayment() Request

Returning User – CVV

Example createPayment() Request – without Nuvei Fields

Example createPayment() Request – with Nuvei Fields

Authorization-Only

Zero-Authorization

Example /openOrder Request

Without Nuvei Fields

Example createPayment() Request

Tokenization-Only

3D-Secure

3D-Secure Authentication Only

Example authenticate3d() Request

Currency Conversion

MCP for Web SDK

DCC for Web SDK

APM

APM Recurring Billing

Example createPayment() Request

Customer Registration via APM

Example createPayment() Request

Apple Pay Web SDK Integrations

Static Apple Pay Button

Dynamic Apple Pay Button

Static Apple Pay Button using Web SDK

Features

Blocking Cards

Example SafeCharge() Function Specifying a blockCards Array

Methods

Get Card Details

Example getCardDetails() Request

Example getCardDetails() Response

Example `createPayment()` Request

Example `createPayment()` Request – without Nuvei Fields

Example `createPayment()` Request – with Nuvei Fields

Example `/openOrder` Request

Example `createPayment()` Request

Example `authenticate3d()` Request

Example `createPayment()` Request

Example `createPayment()` Request

Example `SafeCharge()` Function Specifying a `blockCards` Array

Example `getCardDetails()` Request

Example `getCardDetails()` Response