Getting Started with Web SDK 2.0

Home    Online Payments    Web SDK 2.0 (Beta Release)    Getting Started with Web SDK 2.0

On this page:

Overview

Welcome to Getting Started with Web SDK 2.0, which describes how to accept cards when integrating Nuvei Web SDK 2.0 into your payment page. Web SDK 2.0 supports Nuvei Fields 2.0, which are SDK components that allow you to accept cards without storing the sensitive card detail data yourself.

Additional Resources

Payment (Deposit) Flow

To accept cards when integrating Web SDK 2.0, follow these steps:

  1. Server-to-Server Authentication – Before using the client-side Web SDK 2.0, you need to authenticate your Nuvei merchant details by sending a server-to-server POST /orders REST API 2.0 request.
  2. Frontend Web SDK Initialization – Import the websdk2.0.js library and instantiate Web SDK 2.0.
  3. Nuvei Fields 2.0 Activation – Instantiate Nuvei Fields 2.0; and generate a payment form with the fields embedded.
  4. Frontend Web SDK Card Payment Submission – Send a payment() request with its required parameters, including useFields. If relevant, Nuvei performs a full, end-to-end, and managed 3D Secure (3DS) flow.
  5. Response Verification – Verify the response by sending a GET /entities/{processing-entity-id}/transactions/{transaction-id} REST API 2.0 request or by using webhooks.

1. Server-to-Server Authentication

Before submitting a payment using the client-side Web SDK 2.0, you need to send a server-to-server POST /orders REST API 2.0 request, which:

  • Authenticates your Nuvei credentials.
  • Sets up the authenticated order in the Nuvei system.

To authenticate REST API 2.0 requests, Nuvei uses your API key, which the Nuvei Integration Team provides. Include the API key in the request header:

x-api-key: <your API key>

From your backend server, send a POST /orders request with its mandatory parameters, including:

  • processingEntityId – Processing entity ID provided by Nuvei.
  • amount – Transaction amount.
  • currency – Three-letter ISO currency code.
  • permittedOperations – Array of operations allowed for this order.

Always send the /orders  request from your backend server. Nuvei authenticates the request using your processing entity ID, which should never be exposed on the client side.

Example POST  /orders  Request with Header
POST  /orders HTTPS/1.1 
Host: api.nuvei.com
Content-Type: application/json 
x-api-key: <your API key>

{
  "processingEntityId": "<your processingEntityid>",
  "amount": 10.5,
  "currency": "USD",
  "permittedOperations": [
    "payments"
  ],
  "storePaymentOption": "buyerToken"
}

The response includes sessionId, which you use to authenticate subsequent requests during the session.

Example POST  /orders  Response
{
  "sessionId": "sid_f3a192a9844545d29a11cbc3e3a46bb2",
  "result": {
    "status": "success"
  }
}

2. Frontend Web SDK Initialization

This step and the steps that follow involve integration on your frontend.

Import the websdk2.0.js JavaScript library for building payment flows:

<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/websdk2.0.js"></script>

Instantiate Web SDK 2.0.

Example Instantiating Web SDK 2.0
// Instantiate Nuvei Web SDK 2.0
var nuveiWebSDK = webSDK({
  "env": "int", // int, prod
  "sessionId": "<sessionId from /orders>", // received from /orders API response
  "support19Digits": true, // false (default)
  "alwaysCollectCvv": "optional",
  "blockCards": JSON.stringify(["visa"]), // Visa cards are blocked
  "onResult": function(res) {
    console.log("onResult callback", res);
  }
});

For a compete list of supported nuveiWebSDK() input parameters when instantiating Web SDK 2.0, see Web SDK 2.0 Methods.

3. Nuvei Fields 2.0 Activation

Nuvei Fields 2.0 are SDK components that allow you to accept cards without storing the sensitive card detail data yourself. Activate Nuvei Fields 2.0 and attach them to HTML placeholders. In the example below, the placeholders are card-number,  card-expiry, and card-cvc. When you generate the payment form for a customer, Nuvei replaces the placeholders with our card detail fields.

Example Activating Nuvei Fields 2.0
//Instantiate Nuvei Fields 2.0
var nuveiFields = nuveiWebSDK.fields({
  locale: 'US',
  alwaysCollectCvv: 'optional',
});
window.cardNumber = nuveiFields.create('ccNumber', {
  classes: fieldClasses,
});
window.cardNumber.on('change', function(ccChangeState) {
  console.log(ccChangeState);
});

// Attach Nuvei Fields 2.0 to the HTML placeholders
cardNumber.attach('#card-number');
window.cardExpiry = nuveiFields.create('ccExpiration', {
  classes: fieldClasses,
});
cardExpiry.on('change', function(ccChangeState) {
  console.log(ccChangeState);
});
cardExpiry.attach('#card-expiry');
window.cardCvc = nuveiFields.create('ccCvc', {
  classes: fieldClasses,
});
cardCvc.on('change', function(ccChangeState) {
  console.log(ccChangeState);
});
cardCvc.attach('#card-cvc');

Generate a card payment form with the HTML placeholders.

Example Card Payment Form
<head>
   <title>WebSDK v2.0 payment</title>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/websdk2.0.js"></script> 
</head>
<body>
   <div class="item">
   <div class="row">
      <div class="field"> <label for="cardHolderName">Card Holder Name</label> <input type="text" placeholder="Card Holder Name" id="cardHolderName" name="cardHolderName" value="CL-BRW1" /> </div>
   </div>
   <div class="row">
      <div class="field">
         <label for="card-number"> Card number </label> 
         <div id="card-number" class="input"></div>
      </div>
   </div>
   <div class="row">
      <div class="field">
         <label for="card-expiry"> Expiration Date </label> 
         <div id="card-expiry" class="input"></div>
      </div>
   </div>
   <div class="row">
      <div class="field">
         <label for="card-cvc"> CVV </label> 
         <div id="card-cvc" class="input"></div>
      </div>
   </div>
   <button onclick="main();">Submit Payment</button>
</body>

When designing your payment page, make sure to prevent the customer from initiating the payment process more than once; for example, by pressing the Submit Payment button more than once. Here are some suggestions:

  • When the button is pressed, disable it.
  • When a payment is submitted, disable the screen or the DIV element of the payment form.
  • While Nuvei process the payment, display a progress bar or waiting indication.

The payment form is now completely rendered and ready for the customer to enter card details and other payment information.

4. Frontend Web SDK Card Payment Submission

The customer pressing Submit Payment, for example, activates the payment process.

Send a Web SDK 2.0 payment() request with its mandatory parameters, including:

  • useFields: “ccNumber” – Use the card details Nuvei Fields collected.

If the /orders request did not include country and email, then include them now in the payment() request.

Buyer Details Precedence Rule

In a payment() request, if the merchant includes any values in the billingAddress class (for example, country and email), Nuvei uses those values instead of any values provided in the root of the buyerDetails class.

Example payment() Request
function payment() {
  nuveiWebSDK.payment({
    paymentOption: {
      card: {
        cardHolderName: document.getElementById('cardHolderName').value,
      }
    }
    useFields: 'ccNumber'
  }).then(x => console.log(x))
}

When the payment() process is complete, Nuvei sends a synchronous response to the client side that includes:

  • result.status – Some possible values are:
    • approved – Payment is approved.
    • pending – Payment request is being processed.
    • declined – Payment is declined. Do not proceed with transaction.
    • error – An error occurred.
  • If result.status = “error“, the response also includes result.errors with:
    • code
    • reason
Example Card payment() Response with "status" = “approved”
{
  "paymentId": "687d4c2ccb03427bac754a72c0e5db6b",
  "transactionId": "2110000000015530328",
  "externalTransactionId": "211015530328",
  "amount": 99,
  "currency": "USD",
  "transactionType": "Sale",
  "result": {
    "status": "approved"
  },
  "authCode": "214120",
  "partialApproval": {
    "requestedAmount": 99,
    "requestedCurrency": "USD"
  },
  "paymentOption": {
    "card": {
      "cardHolderName": "CL-BRW1",
      "maskedCardNumber": "5****5761",
      "bin": "511142",
      "last4Digits": "5761",
      "expirationMonth": "03",
      "expirationYear": "33",
      "acquirerId": "99",
      "cardType": "Debit",
      "cardBrand": "MASTERCARD",
      "threeD": {
        "fingerprintUrl": "https://3dsn-qa.nuvei.com/api/ThreeDSMethod/threeDSMethodURL/",
        "fingerprintPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjljYTQzMzEzLTkxNmYtNDgwNC05NGY2LWY4M2JlZTA4M2EzNyIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL2s4cy10bHYtY2wwLWRldi5ndy00dS5jb20vcmVzdC1zZGthZGFwdGVyL3RocmVlRC9zaWRfOTFmZjdmMmMwNjUxNDFmM2E0M2U5MGQ4ZGVlZjU2ZTgvZmluZ2VycHJpbnRpbmdDb21wbGV0ZWQifQ",
        "version": "2.2.0",
        "challengePreferenceReason": "None",
        "acquirerDecision": "ExemptionRequest"
      }
    }
  }
}
Example Card payment() Response with "status" = “declined”
{
    "paymentId": "4f24f65bb01a4fb3bdf5b1d1f37bc536",
    "transactionId": "2110000000015530288",
    "amount": 99,
    "currency": "USD",
    "transactionType": "Sale",
    "result": {
        "status": "declined",
        "errors": {
            "code": "1400.1000",
            "reason": "Do not honor"
        }
    },
    "paymentOption": {
        "card": {
            "cardHolderName": "CL-BRW1",
            "maskedCardNumber": "4****9413",
            "bin": "484511",
            "last4Digits": "9413",
            "expirationMonth": "03",
            "expirationYear": "33",
            "acquirerId": "103",
            "cardType": "Credit",
            "cardBrand": "VISA",
            "threeD": {
                "challengePreferenceReason": "None",
                "acquirerDecision": "ExemptionRequest"
            }
        }
    }
}

For more information about the output parameters in the Web SDK 2.0 payment() response, see Web SDK 2.0 Methods.

After receiving the payment() response, notify your server side and you can display a relevant message to the customer.

Remember that the response is not verified. The server side receives the payment() response from the client side. Therefore, it is vulnerable to manipulation by the end user. You need to verify the response on the server side.

5. Response Verification

Before storing complete payment information in your system, verify the response using one of these methods:

Need Help Deciding?

In general, developers prefer using GET /entities/{processing-entity-id}/transactions/{transaction-id} because the flow is synchronous:

  1. The server side receives a payment() response from the client side.
  2. The server side submits a GET /entities/{processing-entity-id}/transactions/{transaction-id} request.
  3. The server side receives a response.

On the other hand, Nuvei sends webhooks to an endpoint on your system when a transaction or event occurs, in real time. Also, if you are using APMs, use webhooks to verify the response because APM transactions can be asynchronous, involving time delays ranging from a few seconds to several days. After Nuvei receives the final transaction result, Nuvei sends you a webhook with the final result of the transaction.

Send a GET /entities/{processing-entity-id}/transactions/{transaction-id} Request

Send a server-side GET /entities/{processing-entity-id}/transactions/{transaction-id} REST 2.0 API request using the sessionId from the POST /orders response (and also used to initialize Web SDK 2.0 with nuveiWebSDK() ).

You can only send a GET /entities/{processing-entity-id}/transactions/{transaction-id} request:

  • Before the session in which the payment was performed expires. After the session expires, the response is session expired.
  • After the payment() process ends. To detect the end of the process, monitor the JavaScript events for the final transaction event.

Do not use GET /entities/{processing-entity-id}/transactions/{transaction-id} for repeated status polling during the payment() process, which can result in Nuvei blocking your server’s IP address.

Last update iconLast modified March 2025