• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
< BACK TO HOME
  • Online Payments
    • Introduction
    • Choosing an Integration Method
    • Payment Scenarios
    • Flow Diagrams
  • Accept Payment
    • Payment Page (Cashier)
      • Quick Start
      • Input Parameters
      • Output Parameters
      • Payment Page Features
      • Cashier
        • Cashier Events Guide
        • Cashier Features
        • Withdrawal Guide
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Simply Connect
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Simply Connect Examples
      • Server-to-Server
        • REST 1.0
        • Server SDKs
          • Java SDK
          • .NET SDK
          • PHP SDK
          • Node.JS SDK
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Marketplaces
      • Self Track
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion: DCC and MCP
          • Multiple Currency Pricing (MCP)
          • Dynamic Currency Conversion (DCC)
            • DCC in Cashier or Payment Page
            • DCC in REST API Workflows
            • DCC in Web SDK Workflows
        • Payout
        • AFT (Account Funding Transactions)
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscriptions (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
          • Challenges and Exemptions
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Addendums
        • Airline
          • External Authorization
    • Integration
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APMs
        • Testing APIs with Postman
      • Response Handling
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
      • Payment Facilitators (PayFac)
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    Quick Start

    On this page:
    • Overview
    • 1. Initiate a Session
    • 2. Import the Web SDK Library
    • 3. Generate the Payment Form
    • 4. Activate Nuvei Fields
    • 5. Submit a Payment
    • 6. Response Verification
    • Additional Web SDK Functions

    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!

    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.

    Simulating the /openOrder Workflow in the Nuvei Sandbox Environment:

    You can use Postman to simulate the /openOrder workflow (using the “Server to Server with Web SDK” or the “Web SDK API calls” postman collections) in the Nuvei sandbox environment.

    To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

    POST is used for all Nuvei REST API methods that involve a transfer of data from client to server.

    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, that 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 secret key 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 (optional) –
      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, or shippingAddress.
    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

    The next steps involve integration on the frontend.
    For full examples, see the Web SDK Scenarios section, which contains live Web SDK examples using JSFiddle. You can view, modify, and run these examples to test your code.

    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

    When designing your payment page, you must prevent the customer from initiating the payment process twice, for example by pressing the ‘Submit‘ button twice. Here are some suggestions:

    • Disable the button once it has been pressed.
    • Disable the screen or the DIV element of the payment form once a payment is submitted.
    • Display a progress-bar or waiting indication while the payment is being processed.

    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

    If you have your own PCI compliance or filled out the SAQ A-EP, then you do not need to use Nuvei Fields, and you can skip directly to the next step, Submit a Payment, which calls the createPayment() method using the cardholder fields that you collect directly from your own input form.

    In the example below, the placeholder is called “card-field-placeholder”. Nuvei Fields replaces the placeholder fields with the cardholder 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.

    If the mandatory country and email fields were not included earlier in the /openOrder request, then include them now in the createPayment() request.

    Precedence Rule for selecting User-Related Values for a Payment/Authentication

    When processing a createPayment() / authenticate3d() / checkout() request, if you provided any billingAddress values (for example, country and email), then the system uses those values instead of the values provided in the userDetails block.

    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": "john.smith@email.com",
            "country": "US"
          }
      }, function(res) {
            console.log(res);
      })

    Once the createPayment() process ends, you need to notify your server-side.

    The output fields 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 fields 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.

    Since the response from createPayment() is returned from the client-side, it is vulnerable to manipulation by the end-user. Therefore, you need to verify the response on your server-side.

    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.

    2023 Nuvei. All rights reserved.