Overview

Nuvei has the required PCI certification that allows us to store and manage your customers’ payment credentials. When you are using Web SDK 2.0 and a customer makes a payment for the first time:

• Nuvei collects payment credentials. For card payments, Nuvei collects the card details using Nuvei Fields 2.0.
• In the payment() request, you provide buyerId, a unique identifier for the customer in your system.

Upon a successful payment transaction, Nuvei automatically stores the payment details, creates a payment token to represent them, and provides the paymentTokenId in the response.

In future payments and other transactions, you can present a list of the customer’s existing payment methods (payment tokens) in a gallery on the payment page. The customer checkout experience is improved because they simply select a previous payment method instead of providing payment method details again. Then, you include the customer’s buyerId and the corresponding paymentTokenId in the payment() request.

Additional Resources

• What’s new in Nuvei Web SDK 2.0 and the advantages of using it as an integration method – Web SDK 2.0
• Other Nuvei Web SDK 2.0 integration guides:
  • Getting Started with Nuvei Web SDK 2.0 – Card payment
  • Apple Pay
  • Google Pay
  • ACH
• All Web SDK 2.0 methods

Payment (Deposit) Flow

To use an existing payment token when submitting a Nuvei Web SDK 2.0 payment() request, follow these steps:

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 that authenticates your Nuvei merchant credentials and creates a session.
2. Frontend Web SDK Initialization – Import the websdk2.0.js library and instantiate Web SDK 2.0.
3. Payment Page Generation – Generate a payment page with the customer’s existing payment methods.
4. Frontend Web SDK Existing Token Payment Submission – Send a payment() request with its required parameters. If relevant, Nuvei performs a full, end-to-end, 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 that authenticates your Nuvei merchant credentials and creates a session. For details, press here.

2. Frontend Web SDK 2.0 Initialization

For details, press here.

3. Payment Page Generation

Generate a payment page with the customer’s existing payment methods using paymentTokenId and other paymentOption information from previous payment() responses.

The payment page is now completely rendered and ready for the customer to select an existing payment method and provide other payment information.

4. Frontend Web SDK Existing Token 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 the paymentOption.paymentToken class with paymentTokenId and other mandatory parameters.

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 paymentWithPaymentToken() {
  // 33513750-98d1-46fe-a1da-1da2142b67aa
  nuveiWebSDK.payment({
    paymentOption: {
      paymentToken: {
        paymentTokenId: document.getElementById('paymentToken').value,
        additionalData: {
          test: '123',
          test2: '456'
        },
      }
    },
  }).then(console.log);
}

To customize and test an existing payment method scenario using the JSFiddle demonstration environment, see Existing Payment Method Scenario below.

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

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.

5. Response Verification

Before storing complete payment information in your system, you need to verify the response.

For details, press here.

Appendix

Existing Token Payment Scenario

You can use JSFiddle to customize and test the example scenario below.

Using JSFiddle to Customize and Test Scenarios

To customize and test scenarios in JSFiddle:

1. Press Edit in JSFiddle in the top right corner of the JSFiddle widget embedded in this page.
   This redirects you to a page where you can customize and test code.
2. On the JSFiddle page, specify:

   var nuveiWebSDK = webSDK({
     //env: 'int', //  int, prod
     sessionId: orderData.sessionId, // received from POST /orders API request
     support19Digits: true, // false (default)
     alwaysCollectCvv: 'optional',
     blockCards: JSON.stringify(["prepaid"]), // prepaid cards are blocked
     onResult: function(res) {
       console.log('onResult callback', res);
     }
   });

   By default (Classic layout), these settings are in the bottom-left corner:

Feel free to change the code, including the HTML and CSS.