Overview
Introduction
Implementing the Nuvei Web SDK on your payment web page involves running a set of JavaScript scripts, which:
- Initialize 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.
Integrations
Use one of the following integrations to implement the Nuvei Web SDK on your payment web page:
Additional Features
Simple Card Integration
- Import the safecharge.js library.
<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>
- 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>
- 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).
.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; }
- Generate a
sessionToken
by sending calling the /openOrder API. (For details, see: Authenticate and Initiate a Session.) - 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 Merchantsite 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, will try to autodetect })
- 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' } };
- Create a card field and attach to the DOM.
var scard = ScFields.create('card', {style: style}); scard.attach(document.getElementById('card-field-placeholder'));
- Process the card.
// to work with the sample html should be called from within function main() sfc.createPayment({ "sessionToken" : "<sessiontoken>", //received from openOrder API "userTokenId" : "230811147", "clientUniqueId" : "695701003", // optional "cardHolderName" : "card_holder", "paymentOption" : scard, "billingAddress": { "email": "someone@somedomain.com", "country":"GB" } }, function (res) { console.log(res) })
- You can use the
scard
returned in the previous step, to continue process using one of these methods:- createPayment() Web SDK method
- authenticate3d() Web SDK method
- If you prefer to process the payment server-to-server, you can use the getToken() to receive a temporary token (
paymentOption.ccTempToken
field), and then use that in a /payment API call.
createPayment() method
sfc.createPayment({ "sessionToken" : "<sessiontoken>", //received from openOrder API "merchantId" : "1475082432483184221", //as assigned by Nuvei "merchantSiteId" : "184941", //as assigned by Nuvei "userTokenId" : "230811147", "clientUniqueId" : "695701003", // optional "paymentOption" : scard, "billingAddress": { "email": "someone@somedomain.com", "country":"GB" } }, function (res) { console.log(res) })
getToken() method
SafeCharge({ env: 'int', // the environment you are running on, 'prod' for production sessionToken: "<sessionToken>", //session token from getSessionToken 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
In addition to the integration described above, Nuvei Fields offers the same solution, but having the Nuvei Card Field divided into its three building blocks: card number, expiration and CVV. This allows more flexibility with the payment form layouts.
- Import safecharge.js.
<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>
- 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>
- Instantiate Nuvei object.
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 });
- 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 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', };
- 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');
- Process the card.
// this has to be called form within the main() function to work with the sample html sfc.createPayment({ "sessionToken": "<sessionToken>", //received from openOrder API "userTokenId": "230811147", "clientUniqueId": "695701003", // optional "paymentOption": scard, "billingAddress": { "email": "someone@somedomain.com", "country": "GB" } }, function(res) { console.log(res) });
- You can use the
scard
returned in the previous step, to continue process using one of these methods:- createPayment() Web SDK method
- authenticate3d() Web SDK method
- If you prefer to process the payment server-to-server, you can use the getToken() to receive a temporary token (
paymentOption.ccTempToken
field), and then use that in a /payment API call.
createPayment() method
fc.createPayment({ "sessionToken" : "<sessiontoken>", //received from openOrder API "merchantId" : "1475082432483184221", //as assigned by Nuvei "merchantSiteId" : "184941", //as assigned by Nuvei "userTokenId" : "230811147", "clientUniqueId" : "695701003", // optional "paymentOption" : scard, "billingAddress" : { "email": "someone@somedomain.com", "country":"GB" } }, function (res) { console.log(res) })
getToken() method
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" } }