• 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

Nuvei Fields

Contents
  • Overview
  • Simple Card Integration
  • Three-Part Card Field Integration
  • Additional Features
    • Additional Methods
    • Nuvei Fields Custom Styling
      • Supported States
      • Supported Attributes
    • Supported Events
    • Validation Error Handling

Overview

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 Field Integration – This is based on the Simple Card Integration, but offers more flexible payment form layouts.

How implementing the Nuvei Web SDK on your payment web page works:

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, which you can modify and test your own code.

For more details, see the Additional Features topics below:

  • Additional Methods
  • Nuvei Fields Custom Styling
    • Supported States
    • Supported Attributes
  • Supported Events
  • Validation Error Handling

Simple Card Integration

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

  2. 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 will be 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>
  3. 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: Nuvei Fields Stylizing).

    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;
    }
  4. Generate a sessionToken by sending calling the /openOrder API.  (For details, see: Authenticate and Initiate a Session.)
  5. Instantiate the Nuvei Web SDK that hosts 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
    });
  6. 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, will try to autodetect
      })

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

  7. You can create custom styles for the fields and their states (For details, see: Nuvei Fields Stylizing).
    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'
         }
        };
  8. Create a card field and attach to the DOM.
    var scard = ScFields.create('card', {style: style});
        scard.attach(document.getElementById('card-field-placeholder'));
  9. 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": "someone@somedomain.com",
           "country":"GB"
           }
        }, function (res) {
        console.log(res)
      })
  10. 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": "someone@somedomain.com",
             "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', // the environment you are running on, 'prod' for production
        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, will try 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)
           //pass the result.ccTempToken to the server side
          } else {
            console.log(result);
          }
        });
      }

Three-Part Card Field 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.

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

  2. 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>
  3. Generate a sessionToken by sending calling the /openOrder API.  (For details, see: Authenticate and Initiate a Session.)
  4. Instantiate the Nuvei Web SDK that hosts 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
    });
  5. Instantiate Nuvei Fields.
    var ScFields = sfc.fields({
    fonts: [
      { cssUrl: 'https://fonts.googleapis.com/css?family=Roboto' }, // include your custom fonts
      ] 
    })
  6. Create custom styles and classes for Nuvei Fields (see Nuvei Fields Stylizing).
    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',  
     };
  7. 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');
  8. 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": "someone@somedomain.com",
          "country": "GB"
        }
      }, function(res) {
        console.log(res)
      });
  9. 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": "someone@somedomain.com",
             "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
      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
          }
      });

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 Nuvei Fields Stylizing).

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

Supported Events

We support the following events to which you can subscribe:

  • blur
  • change
  • focus
  • ready
sfcCard.on('ready', function (evt) {
      console.log('on sfcCard ready', evt);
});

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

Error Sample:

{  
   "payload":{  
      "cardType":"visa",
      "empty":false,
      "complete":false,
      "error":{  
         "code":"incorrect_card_number",
         "type":"validation_error"
      }
   }
2021 Nuvei. All rights reserved.