Overview
This section discusses additional functions that you can perform with Nuvei Web SDKs.
3D-Secure-Only Request (without payment) – authenticate3d()
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, theeci
value is either 5 (Visa) or 2 (Mastercard). -
cavv
– Upon successful authentication, this will contain the encrypted authentication value, otherwise it will be either empty or null.
Example authenticate3d() Request
// Instantiate Nuvei API var sfc = SafeCharge({ env: 'test', // 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 }); 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": "25", "CVV": "217" } }, "billingAddress": { "email": "someone@somedomain.com", "country": "GB" } }, function(result) { console.log(result.cavv) }); }
Web SDK (without Nuvei Fields) – createPayment()
If you would rather not use Nuvei Fields, you can provide the cardholder information directly and charge your customer using the createPayment() method, as shown in the example below.
Example createPayment() Request
// Instantiate Nuvei API var sfc = SafeCharge({ env: 'test', // 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 }); 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) }); }
Authorization-Only – openOrder
There are two ways to perform authorization-only requests with Web SDK:-
Zero-Authorization
- Authorize a zero amount.
Perform a zero amount transaction as follows:
This is used to verify a card or add a card to your customer’s account for future use.
-
- Call the /openOrder method and set amount=0 and transactionType=Auth.
Example openOrder Request
{ "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "487106", "clientUniqueId": "12345", "clientRequestId": "1484759782197", "currency": "USD", "transactionType": "Auth", "amount": "0", "timeStamp": "20170118191751 ", "checksum": "6b53666fc048a825be63cbb820da467b" }
- From your client-side, call a createPayment() or an authenticate3d() request. Use the
sessionToken
returned from the /openOrder, and set theamount
field to zero, as described in the Quick Start section.
- Call the /openOrder method and set amount=0 and transactionType=Auth.
- Authorize a zero amount.
Tokenization-Only
Overview
This section describes how to implement a tokenization-only flow.
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.
Tokenization-only Flow Integration Steps
- Step 1. Authenticate the Merchant – Sets up an order in the Nuvei system.
- Step 2. Perform Tokenization-only using the Web SDK – Perform Tokenization-only using the Nuvei Web SDK getToken() method.
- Step 3. Submit a Payment (Non-3D) – Submit a /payment API request using the Nuvei client-side Web SDK.
Step 1: Authenticate the Merchant
Generate a sessionToken
by posting a /getSessionToken API server-side call, and include the checksum
field.
Example /getSessionToken Request
{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId": "<The ID of the API request in the merchant’s system>", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example /getSessionToken Response
The response returns the sessionToken
which you will need for authentication in all subsequent calls in the flow.
{ "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0", "internalRequestId": 188635168, "status": "SUCCESS", "errCode": 0, "reason": "", "merchantId": "479748173730597238", "merchantSiteId": "180083", "version": "1.0", "clientRequestId": "20200510165419" }
Step 2. Perform Tokenization-only using the Web SDK
Perform Tokenization-only using the Nuvei Web SDK getToken() method which tokenizes the card and cvv, and returns the ccTempToken
.
You can then use the ccTempToken
to process the payment using the /payment API method.
Example of getToken() Request
var sfc = SafeCharge({ env: 'int', // the environment you are running on (if omitted, default is 'prod') 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 we will try to 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.paymentOption.ccTempToken) // pass the paymentOption block, as is, to the payment API call } else { // handle error. } }); }
Step 3. Submit a Payment (Non-3D)
You can submit a /payment API request (3D-Secure or Non-3D Secure) using the Nuvei client-side Web SDK, using the ccTempToken
returned by the getToken() method.
This example shows a Non-3D Secure payment.
Example /payment Request (Non-3D)
{ "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb", "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"1C6CT7V1L", "amount":"10", "currency":"USD", "userTokenId":"487106", "clientUniqueId":"12345", "paymentOption":{ "card":{ "ccTempToken":"c0275892-fce1-488f-9268-1c826b2574e8" } }, "deviceDetails":{ "ipAddress":"93.146.254.172" }, "timeStamp":"20191105081132", "checksum":"5582d0189dd440f4bbf960569ec22e77" }
Existing User (with no cardholder data 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() functions. 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.
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', // the environment you are running on (if omitted, default is 'prod') 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); }); }
Existing User, Collecting only 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.
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', // the environment you are running on (if omitted, default is 'prod') 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', // 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 }); 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); }) }
DCC in Web SDK
You can use DCC in Web SDK payment requests, by calling the clientGetDccDetails
Web SDK method.
The Web SDK will retrieve DCC information based on the previously received payment method, source amount, source currency and target currency.
The output of this method will be the complete DCC information.
Invoke this by sending a clientGetDccDetails
Web SDK request.