On this page:

Overview

Nuvei SDKs contain sets of components for building checkout flows, which are ready to collect user data. Nuvei Fields are SDK components that allow you to tokenize sensitive data from within the SDKs, without needing to communicate with your server.

Features

Card brand identification
PCI compliance with SAQ A
Customizable styling to match the look and feel of your payment page
Responsive design that fits all your customer’s devices
Field placeholders that match your customer’s preferred language
Field formatting and masks
Real-time input validation
Error messages
Predefined events to which you can subscribe
You can invoke a set of predefined methods on Nuvei Fields
Accessibility support
Localized messages and placeholders
Web fonts support
Click-targets automatic set on labels for seamless integration

Implementing Nuvei Web SDK

You can implement the Nuvei Web SDK on your payment web page using either of these integrations as described below:

Simple Card Integration
Three-Part Card Fields Integration – This is based on the Simple Card Integration but offers more flexible payment form layouts.

How to Implement the Nuvei Web SDK

Implementing the Nuvei Web SDK on your payment web page involves running a set of JavaScript scripts, which:

Initializes the Nuvei Web SDK and the Fields objects.
Inserts the payment Nuvei Fields into your payment form for secure collection.
Stylizes the Nuvei Fields using style classes with your own look and feel.
Collects cardholder information.
Submits card information for tokenization.

You can refer to the Web SDK Samples page, which contains live Web SDK samples using JSFiddle. There are many code samples that you can modify to test your own code.

Simple Card Integration

Creating a Form

Import the safecharge.js library.
```
<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>
```
The script must be loaded from the Nuvei CDN. It must not be saved to or loaded from the client server.

Create a simple container for your form.

<html>
  <head>
    <script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>
  </head>
  <body>
    <form action="/charge" method="post" id="payment-form">
      <div class="form-row">
        <label for="card-field-placeholder">
         Credit or debit card
        </label>
        <div id="card-field-placeholder" class="some initial css-classes">
          <!-- SFC Card widget is inserted here. -->
        </div>
        <!-- Used to display form errors. -->
        <div id="scard-errors" role="alert"></div>
      </div>
    </form>
    <button onclick="main();">Submit Payment</button>
  </body>
</html>

Customize by defining classes for sizes and states. Nuvei Fields implements these classes and you can stylize the fields by setting these classes (for details, see Styling).

In addition, you can define the styles as variables, as shown below.

.SfcFields {
    background-color: #feff8c;
    height: 42px;
    padding: 10px 12px;
    border-radius: 4px;
    border: 1px solid transparent;
    box-shadow: 0 1px 3px 0 #e6ebf1;
    -webkit-transition: box-shadow 150ms ease;
    transition: box-shadow 150ms ease;
}
.sfc-empty {
    background-color: #fecd58 !important;
}
.sfc-empty.sfc-focus {
    box-shadow: 0 1px 3px 0 #cfd7df;
    background-color: #fe8423 !important;
}
.sfc-focus {
    box-shadow: 0 1px 3px 0 #cfd7df;
    background-color: #feb1c7 !important;
}
.sfc-complete {
    background-color: #34fa29 !important;
}
.sfc-invalid {
    border-color: #fa755a;
}
.SfcFields--webkit-autofill {
    background-color: #fefde5 !important;
}

Creating a Card Field

Generate a sessionToken by calling the /openOrder API. (For details, see Initiate a Session.)

Instantiate the Nuvei Web SDK that hosts 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
});

Instantiate Nuvei Fields.
```
var ScFields = sfc.fields({
  fonts: [
    { cssUrl: 'https://fonts.googleapis.com/css?family=Source+Code+Pro' }, // include your custom fonts
    ],
    locale: 'de',// You can set users' preferred locale. If not provided, tries to auto-detect.
    textDirection:'ltr', // or rtl
  })
```
The following languages are supported by Nuvei Fields:
en (English), de (German), da (Danish), fr (French), el (Greek), es (Spanish), et (Estonian), lv (Latvian), lt (Lituanien), fi (Finish), pl (Polish), bg (Bulgarian), ro (Romanian), it (Italian), sv (Swedish), no (Norwegian), nl (Dutch), hr (Croatian), hu (Hungarian), he (Hebrew), ar (Arabic), ja (Japanese), zh (Chinese), tr (Turkish), vi (Vietnamese), sr (Serbian), pt (Portuguese), ru (Russian).

You can create custom styles for the fields and their states (for details, see Styling).

var style = {
     base: {
        fontSize: '16pt',
        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: '#48ef39'
     }
    };

Create a card field and attach to the DOM.

var scard = ScFields.create('card', {style: style});
    scard.attach(document.getElementById('card-field-placeholder'));

Processing a Card

Process the card.

The cardHolderName must appear in the top-level of the object that is passed into createPayment().

// to work with the sample html should be called from within function main()
sfc.createPayment({
    sessionToken   : "<sessiontoken>", //received from openOrder API
    clientUniqueId : "695701003", // optional
    cardHolderName  : "<card_holder>",
    paymentOption  : scard,
    billingAddress: {
       email: "[email protected]",
       country:"GB"
       }
    }, function (res) {
    console.log(res)
  })

You can use the scard returned in the previous step to continue process using any of these methods:

The createPayment() Web SDK method or the authenticate3d() Web SDK method.

Example `createPayment()` Request

sfc.createPayment({
    sessionToken   : "<sessiontoken>", //received from openOrder API
    merchantId     : "<your merchantId>", //as assigned by Nuvei
    merchantSiteId : "<your merchantSiteId>", //as assigned by Nuvei
    clientUniqueId : "695701003", // optional
    paymentOption  : scard,
    billingAddress: {
       email: "[email protected]",
       country:"GB"
     }
  }, function (res) {
 console.log(res)
})

Another option is to use the /payment API call (server-to-server).
To do so, first call the getToken() Web SDK method to receive a temporary one-time paymentOption.ccTempToken, and then use it in a /payment API call.

Example `getToken()` Request

SafeCharge({
  env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
  sessionToken: "<sessionToken>", //received from openOrder API
  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, tries to auto-detect.
});
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)
     //pass the result.ccTempToken to the server side
    } else {
      console.log(result);
    }
  });
}

Example JSFiddle – Simple Card

Three-Part Card Fields Integration

Another integration option is based on the Simple Card Integration described above but offers more flexible payment form layouts. This is made possible by dividing the Nuvei Card Fields into their three building blocks: card number, expiration and CVV.

Creating a Form for Three-Part Card Fields

Import the safecharge.js library.
```
<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>
```
The script must be loaded from the Nuvei CDN. It must not be saved to or loaded from the client server.

Create a template for the three-part Nuvei Fields.

<html>
  <head>
    <script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>
  </head>
  <body>
    <form action="/charge" method="post" id="payment-form">
      <div class="row">
        <div class="field">
          <div id="card-number" class="input"></div>
          <label for="card-number" data-tid="scwsdk.form.card_number_label">
            Card number
          </label>
          <div class="underline"></div>
        </div>
      </div>
      <div class="row">
        <div class="field col6">
          <div id="card-expiry" class="input empty"></div>
          <label for="card-expiry" data-tid="scwsdk.form.card_expiry_label">
            Expiration
          </label>
          <div class="underline "></div>
        </div>
        <div class="field col6">
          <div id="card-cvc" class="input empty"></div>
          <label for="card-cvc" data-tid="scwsdk.form.card_cvc_label">
            CVC
          </label>
          <div class="underline "></div>
        </div>
      </div>
    </form>
      <button onclick="main()">Submit Payment</button>
  </body>
</html>

Creating Three-Part Card Fields

Generate a sessionToken by calling the /openOrder API. (For details, see Initiate a Session.)

Instantiate the Nuvei Web SDK that hosts 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
});

Instantiate Nuvei Fields.

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

Create custom styles and classes for Nuvei Fields (see Styling).

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',  
 };

Create and attach fields to the DOM.

var scard= ScFields.create('ccNumber', {
    style: ScFieldStyles,
    classes: ScFieldClasses,
});
scard.attach('#card-number');

var cardExpiry = ScFields.create('ccExpiration', {
    style: ScFieldStyles,
    classes: ScFieldClasses,
});
cardExpiry.attach('#card-expiry');

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

Processing Three-Part Card Fields

Process the card.

The cardHolderName must appear in the top-level of the object that is passed into createPayment().

// this has to be called form within the main() function to work with the sample html
  sfc.createPayment({
    sessionToken: "<sessionToken>", //received from openOrder API
    clientUniqueId: "695701003", // optional
    cardHolderName : "<card_holder>",
    paymentOption: scard,
    billingAddress: {
      email: "[email protected]",
      country: "GB"
    }
  }, function(res) {
    console.log(res)
  });

You can use the scard returned in the previous step to continue process using any of these methods:

The createPayment() Web SDK method or the authenticate3d() Web SDK method.

Example `createPayment()` Request

sfc.createPayment({
    sessionToken   : "<sessiontoken>", //received from openOrder API
    merchantId     : "<your merchantId>", //as assigned by Nuvei
    merchantSiteId : "<your merchantSiteId>", //as assigned by Nuvei
    clientUniqueId : "695701003", // optional
    paymentOption  : scard,
    billingAddress: {
       email: "[email protected]",
       country:"GB"
     }
  }, function (res) {
 console.log(res)
})

Example `getToken()` Request

sfc.getToken(scard).then(function(result) {
    // Stop progress animation!
    if (result.status === 'SUCCESS') {
        // use result.paymentOption to pass, as is, to the /payment API method
    } else {
        // Otherwise, re-enable input. Handle error
    }
});

Example JSFiddle – Three-Part Card Fields

Additional Features

There are methods for enabling additional functionalities and custom styling for Nuvei Fields.

Additional Methods

The following additional methods are available to instruct Nuvei Fields to perform the corresponding functionalities:

destroy – Removes Nuvei Fields from your page
clear – Erases your customers input from Nuvei Fields
focus – Selects the element and your customer can start typing. An example of selecting an element and invoking the method:

document.getElementById("SfcFields").addEventListener('click', function (ev) {
      ev.preventDefault();
      SfcFields.destroy();
  });

Nuvei Fields Custom Styling

Supported States

We support custom styling for four states of Nuvei Fields (see Styling).

var customStyles = {
      base: {
      },
      empty: {
      },
      valid: {
      },
      invalid: {
      },
   };

Supported Attributes

We support the following attributes for custom styling:

color
fontFamily
fontSize
fontSmoothing
-webkit-font-smoothing
-moz-osx-font-smoothing
fontStyle, fontVariant
fontWeight
lineHeight
letterSpacing
textAlign
textDecoration
textShadow
textTransform
::placeholder
::selection
::-ms-clear
:-webkit-autofill
:disabled
:focus
:hover
opacity
display

Validation Error Handling

For each change to Nuvei Fields, the Web SDK sends “change” events, which provide the following information about the Fields status:

cardType – visa, mastercard, amex, diners, discover, jcb, dankort, unionPay
complete – Boolean. Indicates if the full card information is complete and valid.

Error events:

error – with the following attributes:
- Type – validation_error.
- Code – the specific error code:
  - incomplete_cvc – missing or incomplete CVV/CVC
  - incomplete_date – missing or incomplete date
  - date_in_past – date is in the past
  - invalid_expiration_year – invalid year value
  - incomplete_card_number – incomplete or missing card number
  - incorrect_card_number – incorrect card number

Example Error

{  
   "payload":{  
      "cardType":"visa",
      "empty":false,
      "complete":false,
      "error":{  
         "code":"incorrect_card_number",
         "type":"validation_error"
      }
   }

Nuvei Fields Events

We support the following events to which you can subscribe:

blur
change
focus
ready

scard.on('ready', function (evt) {
      console.log('on scard ready', evt);
});

Nuvei Fields

Overview

Features

Implementing Nuvei Web SDK

How to Implement the Nuvei Web SDK

Simple Card Integration

Creating a Form

Creating a Card Field

Processing a Card

Example createPayment() Request

Example getToken() Request

Example JSFiddle – Simple Card

Three-Part Card Fields Integration

Creating a Form for Three-Part Card Fields

Creating Three-Part Card Fields

Processing Three-Part Card Fields

Example createPayment() Request

Example getToken() Request

Example JSFiddle – Three-Part Card Fields

Additional Features

Additional Methods

Nuvei Fields Custom Styling

Supported States

Supported Attributes

Validation Error Handling

Example Error

Nuvei Fields Events

Example `createPayment()` Request

Example `getToken()` Request

Example `createPayment()` Request

Example `getToken()` Request