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.
• Always send the /openOrder request from your backend server because the checksum 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 your merchantSecretKey at the end.
• country and email
  If these are not provided here, then they must be included later in a createPayment() / 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 classes: userDetails, billingAddress, or shippingAddress.
• 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 and errorDescription: 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 the sessionToken (returned from the /openOrder, which you previously used in createPayment()).
  This returns the complete verified payment response, which includes additional information about the payment and the card used.
  
  
  The /getPaymentStatus can only be called while the session in which the payment was performed is still open. Once the session expires, you receive a “session expired” response.

  The /getPaymentStatus method can only be called at the end of payment processing for that payment. (You can detect the end of payment processing by monitoring the JavaScript events for the final transaction event.)getPaymentStatus is not intended for repeated status polling during the payment processing. Doing so may result in your IP address being blocked.

• 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 Response

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