Web SDK Additional Functions

On this page:

Overview

These topics  discuss many of the functions that can be performed using Nuvei Web SDKs.

For full examples, see the Web SDK Scenarios section, which contains live Web SDK examples using JSFiddle. You can view, modify, and run these examples to test your code.

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 offer returning customers the option to select a payment method from one of their previously stored payment methods.

Retrieving stored cardholder information – To retrieve the userPaymentOptionId, specify the userTokenId field when calling the createPayment() or authenticate3d() methods. The response identifies the customer, and guarantees that the payment methods (cards) returned, belong to that customer.
(The userPaymentOptionId and the userTokenId parameters should be included in initial calls and any 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

An authorization is the first step in an “Auth-Settle” flow. It applies a temporary hold on funds in the customer’s selected payment method (card) account, for a limited timeframe, to ensure there are sufficient funds to settle the payment.

To complete the purchase, the authorization must be followed by one or more REST API settle requests.
For example, a travel agent can send an authorization-only transaction when booking an airplane ticket. Later, they can send a REST API settle request to complete the transaction.

Alternatively you can send a REST API void request to cancel the temporary hold.

Perform an authorization-only transaction as follows:

  1. First send an /openOrder request and set 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":"500",
    "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'            => '500',
    '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 = "500";
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",
 "500",
 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'           : '500'
    'transactionType' : 'Auth',
    'userTokenId' : '230811147',
    'billingAddress': {
        'email': "john.smith@email.com",
        'country': "US"
    },
}, function (err, result) {
    console.log(err, result)
});
  2. Then, from your client-side, use the sessionToken returned from the /openOrder, to send a createPayment() or an authenticate3d() request, and set transactionType="Auth".

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 (tokenize the card), by simply sending a “zero” amount transaction.

Perform a zero amount transaction as follows:

  1. 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)
});
  2. Then, from your client-side, use the sessionToken returned from the /openOrder to send a createPayment() or an authenticate3d() request, and set the amount=0 and transactionType=Auth.

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

Without Nuvei Fields

You can send the cardholder details directly in a createPayment() request without using Nuvei Fields, as shown in the example below.

For your convenience, it is recommended to use Nuvei Fields to collect cardholder details.
However, if you decide to collect cardholder details on your own, you are required to complete a PCI SAQ A -EP form, commit to various additional security measures, and 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 that 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 payments.

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 that 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 MCP 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 for adding the Apple Pay payment method to your websites and applications.
See full integration details in these topics:

Features

Blocking Cards

You can block cards from being included in requests, or from 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 blocking list. For full details, see the Blocking Cards topic.

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: [["visa","credit","corporate"],["amex","GB"]]  //blocks Visa corporate credit cards, and also blocks British Amex cards
});

There is an “intersection” relationship between card attributes in the blocking list.
For example: [“amex”, “credit”, “corporate”] excludes only “Amex corporate credit” 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 cardNumber or a 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"
}