Overview
The Nuvei Web SDK is a JavaScript library of API methods that you can use to accept payments on your own payment page, as part of your own custom payment flow.
Using the Web SDK provides:
- Full PCI compliance – Enjoy PCI compliance, simple implementation with minimum effort.
- End-to-end payment process in one call – A simple call using the Web SDK
createPayment()
method processes your 3D-Secure payment, end-to-end, and meets all the PCI requirements.
This guide steps you through the Web SDK integration process.
Visit our Web SDK Demo Site
Press this button to visit our Web SDK demo site!
Getting Started
Follow the steps in the topics below to integrate Web SDK into your payment page before you can submit a payment with the Nuvei client-side Web SDK.
1. Initiate a Session
Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder
API call.
Prerequisites and Notes for the /openOrder
Request
- The server-side
/openOrder
API request does the following:- Authenticates your Nuvei merchant credentials.
(You can log in to the Nuvei Control Panel using your username and password to find your credentials here.) - Sets up the authenticated order in the Nuvei system, and returns a
sessionToken
which is needed to send other requests in the session.
- Authenticates your Nuvei merchant credentials.
- Always send the
/openOrder
request from your backend server because thechecksum
parameter calculation includes your secret key, which should NOT be exposed on the client side.
Sending an /openOrder
Request
On the server-side, send an /openOrder
request with its mandatory parameters, and include the following:
checksum
This is a SHA-256 encrypted string that you create, which is used for request authentication. You can calculate it by performing a SHA-256 encryption on a string of these concatenated fields, in the following order:
merchantId
,merchantSiteId
,clientRequestId
,amount
,currency
,timeStamp
, and yourmerchantSecretKey
at the end.country
andemail
If these are not provided here, then they must be included later in acreatePayment()
/authenticate3d()
request.urlDetails.notificationUrl
(recommended)
The URL to which DMNs can be sent.preventOverride
=”1” (optional)
This prevents future requests from over-writing values contained in these blocks:userDetails
,billingAddress
, orshippingAddress
.sessionCardDeclineLimit
(optional)
This parameter controls the number of transaction declines that can be received during a single session. If this limit of declines is reached, the session expires immediately.
Example /openOrder
Request
{ "merchantId":"<your merchantId goes here>", "merchantSiteId":"<your merchantSiteId goes here>", "clientUniqueId":"<unique transaction ID in merchant system>", "clientRequestId":"<unique request ID in merchant system>", "currency":"USD", "amount":"200", "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 system>', 'clientRequestId' => '<unique request ID in merchant system>', 'currency' => 'USD', 'amount' => '200', ]); ?>
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, APIConstants.Environment.INTEGRATION_HOST.getUrl(), Constants.HashAlgorithm.SHA256); //for openOrder String clientUniqueId = "<unique transaction ID in merchant system>"; String clientRequestId = "<unique request ID in merchant system>"; String currency = "USD"; String amount = "200"; Safecharge safecharge = new Safecharge(); SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId, clientUniqueId, null, null, null, null, currency, amount, null, null, null, null, null, null, null, null, null, null, null, null, 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", "200", clientUniqueId: "<unique transaction ID in merchant system>", clientRequestId: "<unique request ID in merchant system>", );
const safecharge = require('safecharge'); safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>); safecharge.paymentService.openOrder({ 'clientUniqueId' : '<unique transaction ID in merchant system>', 'clientRequestId' : '<unique request ID in merchant system>', 'currency' : 'USD', 'amount' : '200' }, function (err, result) { console.log(err, result) });
Example /openOrder
Response
{ "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b", "orderId": "39272", "merchantId": "427583496191624621", "merchantSiteId": "142033", "clientUniqueId": "12345", "clientRequestId": "1484759782197", "internalRequestId": 866, "status": "SUCCESS", "errCode": 0, "reason": "", "version": "1.0" }
2. Import the Web SDK Library
safecharge.js
is a JavaScript library for building payment flows. It allows you to collect sensitive data from the user and create representative Tokens for safely sending that data to your servers. This allows a PCI-descoped way to collect and process card details.
Import the safecharge.js
JavaScript library:
<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>
3. Generate the Payment Form
Create your payment form with a Nuvei Fields placeholder, which can be customized (see Nuvei Fields Styling).
Example Payment 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>
4. Activate Nuvei Fields
Use our API to inject Nuvei Card Fields:
// 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 }); //Instantiate Nuvei Fields var ScFields = sfc.fields({ fonts: [ { cssUrl: ''} ] // e.g. https://fonts.googleapis.com/css?family=Source+Code+Pro }) // set state field style/ check Nuvei Fields for details. var style = { /* state styles */ }; // Instantiate Nuvei Fields var scard = ScFields.create('card', {style: style}); // attach the Nuvei fields to the html placeholder scard.attach(document.getElementById('card-field-placeholder'));
By the end of this step, the form is completely rendered and ready for the customer to enter their cardholder details and other payment information. By pressing the ‘Form‘ button, the customer activates the payment process and submits the response to your server.
5. Submit a Payment
The customer enters their cardholder details and other payment information and presses the ‘Submit‘ button.
Send a createPayment()
request with its mandatory parameters and the data collected using the Nuvei fields. This performs an end-to-end payment process.
Example createPayment()
Request
// call this from your main() in order for it to work with the html sample sfc.createPayment({ "sessionToken": "{as received from openOrder}", "clientUniqueId": "<unique transaction ID in merchant system>", // optional "cardHolderName": "john smith", "paymentOption": scard, "billingAddress": { "email": "[email protected]", "country": "US" } }, function(res) { console.log(res); })
Once the createPayment()
process ends, you need to notify your server-side.
The output parameters returned include:
transactionStatus
: Values can be either APPROVED, DECLINED, or ERROR (in case of any error).errCode
anderrorDescription
: In the case of an error, these parameters contain the decline reason and error description.
For the complete response details see the /payment
output parameters table.
Example createPayment()
Response
{ "result": "APPROVED", "errCode": 0, "errorDescription": "", "userPaymentOptionId": "14958143", "ccCardNumber": "5****5761", "bin": "511142", "last4Digits": "5761", "ccExpMonth": "09", "ccExpYear": "21", "transactionId": "1110000000004146935", "threeDReason": "", "threeDReasonId": "", "challengeCancelReasonId": "", "challengeCancelReason": "", "isLiabilityOnIssuer": "1", "challengePreferenceReason": "12", "cancelled": false }
6. Response Verification
Verify the payment response received on your server-side before storing the complete payment information in your system.
Verify the response using one of these methods:
- Call
/getPaymentStatus
API from your server-side using thesessionToken
(returned from the/openOrder
, which you previously used increatePayment()
).
This returns the complete verified payment response, which includes additional information about the payment and the card used.
-
Example
/getPaymentStatus
Request{ "sessionToken": "<sessionToken from /openOrder>" }
<?php $getPaymentStatusRequest = $SafeCharge->getPaymentService()->getPaymentStatus([ 'sessionToken' => '274ff0d9-c859-42f5-ae57-997641f93471', ]); ?>
public class ExampleGetPaymentStatus { public static void main(String[] args) { GetPaymentStatusResponse response = safecharge.getPaymentStatus(); } }
//Start by initializing the SDK. For more details, see the Nuvei .NET SDK at https://docs.nuvei.com/?p=48413. // preceded by payment request var response = safecharge.GetPaymentStatus();
Example
/getPaymentStatus
ResponseFor a full description of responses, refer to
/getPaymentStatus
.{ "transactionStatus": "APPROVED", "gwExtendedErrorCode": 0, "errorCode": 0, "reason": "", "authCode": "075449", "clientRequestId": "9WD9JCZW9", "internalRequestId": 13004281, "version": "1.0", "transactionId": "2110000000001496240", "amount": "200", "currency": "USD", "merchantSiteId": "142033", "transactionType": "Sale", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "userPaymentOptionId": "7072706", "card": { "uniqueCC": "NuBcbNkc7kBwNExS5j/wgIS8sNk=" } }, "sessionToken": "64fe6953-69d1-440f-8e21-878c85701f09", "userTokenId": "230811147", "status": "SUCCESS" }
- Alternatively, you can use our DMN system to verify the response. In this case, you receive a direct notification to the webhook endpoint on your system. Details for the payment are received as shown in the following example.
{ "result": "APPROVED", "errCode": 0, "errorDescription": "", "userTokenId": "230811147", "userPaymentOptionId": "18390993", "ccCardNumber": "4****3335", "bin": "401200", "last4Digits": "3335", "ccExpMonth": "09", "ccExpYear": "21", "transactionId": "1110000000003862135", "cancelled": false }
Additional Web SDK Functions
Nuvei Web SDK offers many other payment functions and options. For details, see the Web SDK Additional Functions topic.