On this page:

Overview

The Nuvei Web SDK allows you to code in ReactJS to accept payments on your own payment page as part of your own custom payment flow.

Using the Web SDK provides:

Full PCI compliance – with minimum effort and simplest implementation.
End-to-end payment process in one call. Simply calling 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 using ReactJS.

Follow the Web SDK integration steps below before you can submit a payment with the Nuvei client-side Web SDK:

Initiate a Session
Initialize Web SDK
Generate the Payment Form –
You can create a Payment Form with or without Nuvei Fields, to collect customer card details on your own input form:
- Create a Payment Form with Nuvei Fields
- Create a Payment Form (no Nuvei Fields) – For example, this can be used by merchants implementing 3D-Secure and have their own PCI compliance, or use the SAQ A-EP.

Let’s get started…

Initiate a Session

See the Web SDK Initiate a Session topic.

Initialize Web SDK

Load and initialize Web SDK and set the Safecharge Props as described below.

When designing your custom payment flow, there are many ways of using ReactJS to collect payment details on your own payment page, and send them for processing.

For your convenience, we have provided the following sets of ReactJS code samples and functional sandbox examples:

All the ReactJS related steps described in this topic are based on the following code samples:

ReactJS Code – Full Samples:
ReactJS Code – Sandbox Examples:
You can try-out the sample Web SDK Flow ReactJS code in a sandbox:

Create a ReactJS main app and ReactJS component, as described below:

Create a ReactJS main app. (In our example we name it: “App.js“.)
(To see a full example, see the Example App.js topic.)
Create a .jsx file (JavaScript Extension) to contain ReactJS components etc. (In our example we name it: “SafeCharge.jsx“.)
(To see a full example, see the Example SafeCharge.jsx topic.)
In the App.js file, load and initialize the Web SDK Library (safecharge.js).
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.

Example App.js – Load and Initialized Web SDK and Set Safecharge Props
```
  useEffect(() => {
    loadScript(
      "https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js" //production
    ).then(() => {
      setSafeCharge(
        window.SafeCharge({
          merchantId: "806659927845195034",
          merchantSiteId: "196488"
        })
      );
    });
  }, []);
```
Add a core component and pass safecharge as an HTML prop (property). (In our example we name it: "safeChargeCC".)

Example App.js – Add “safeChargeCC” Component and Pass safecharge as an HTML Prop
```
  return (
    <div className="App">
      <SafeChargeCC safeCharge={safeCharge} />
    </div>
  );
```

Payment Form with Nuvei Fields

Nuvei Fields can be customized, see Styling for details.

When designing your payment page, you must prevent the customer from initiating the payment process twice, for example by pressing Submit 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.

1. Create the HTML Tags

Create the HTML Tags for the Web SDK Properties.

The following example SafeCharge.jsx code shows the creation of the HTML Tags for the Web SDK properties.

Example SafeCharge.jsx Code

import React, { memo, useEffect, useState } from "react";

export const SafeChargeCC = memo(({ safeCharge }) => {
  const [cardN, setCardN] = useState(null);
  const [sessionToken, setSessionToken] = useState("");
  const [cardHolderName, setCardHolderName] = useState("CL-BRW1");

  useEffect(() => {
    if (safeCharge) {
      const safeChargeFields = safeCharge.fields({
        fonts: [{ cssUrl: "" }],
        locale: "en",
        fontSize: "16px"
      });

      // Card number----------------------------------------------------

      const cardNumber = safeChargeFields.create("ccNumber", {
        // style: {
        //   base: {
        //     fontSize: "16px"
        //   }
        // }
      });

      cardNumber.attach("#card-number");

      const cardExpiry = safeChargeFields.create("ccExpiration", {
        style: {
          base: {
            fontSize: "16px"
          }
        }
      });

      // cardExpiry.on("change", (evt) => {
      //   console.log("cardExpiry change event >>>", evt);
      // });

      // cardExpiry.on("error", (evt) => {
      //   console.log("cardExpiry error event >>>", evt);
      // });

      cardExpiry.attach("#card-expiry");

      // CVV--------------------------------------------------------------

      const cardCvc = safeChargeFields.create("ccCvc", {
        style: {
          base: {
            fontSize: "16px"
          }
        }
      });

      cardCvc.attach("#card-cvc");
      console.log(cardNumber);
      setCardN(cardNumber);
    }
  }, [safeCharge]);

import React, { memo, useEffect, useState } from "react";

export const SafeChargeCC = memo(({ safeCharge }) => {
  const [cardNumber, setCardNumber] = useState(null);
  const [sessionToken, setSessionToken] = useState("");
  const [cardHolderName, setCardHolderName] = useState("CL-BRW1");

  useEffect(() => {
    if (safeCharge) {
      const safeChargeFields = safeCharge.fields({
        fonts: [{ cssUrl: "" }],
        locale: "en"
      });

      // Card number----------------------------------------------------

      const cardNumber = safeChargeFields.create("card", {});

      cardNumber.attach("#card-field");

      setCardNumber(cardNumber);
    }
  }, [safeCharge]);

2. Sending the Request

The customer enters their cardholder details and other payment information, and presses Submit.

Use the Nuvei fields containing the data collected to invoke the createPayment() method, which performs the end-to-end payment process.
Alternatively, you can perform a 3D-Secure authentication by calling the authenticate3d() method (which has the same input and output parameters as the createPayment() method).

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

Example `createPayment()` / `authenticate3d()` Request

const createPayment = (e) => {
  if (cardN) {
    try {
      safeCharge.createPayment(
        {
          sessionToken: sessionToken,
          cardHolderName: cardHolderName,
          paymentOption: cardN,
          billingAddress: {
            email: "[email protected]",
            country: "GB"
          }
        },
        (resp) => console.log(resp)
      );
    } catch (e) {
      console.error(e);
    }
  }
};

const authenticate3d = (e) => {
  if (cardN) {
    try {
      safeCharge.authenticate3d(
        {
          sessionToken: sessionToken,
          cardHolderName: cardHolderName,
          paymentOption: cardN,
          billingAddress: {
            email: "[email protected]",
            country: "GB"
          }
        },
        (resp) => console.log(resp)
      );
    } catch (e) {
      console.error(e);
    }
  }
};

When the createPayment() process is complete then notify your server side.
The output fields returned include:

transactionStatus: Values can be either APPROVED, DECLINED, or 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 createPayment() output parameters.

Example `createPayment()` Response

{
  authCode: "111010"
  checksum: "65cb9dbe77ef8445b3614a8d65c2fd6113173b236480a217eb31f35afd16687e"
  customData: ""
  errCode: 0
  externalTransactionId: ""
  fraudDetails: {
    finalDecision: "Accept"
  }
  gwErrorCode: 0
  gwExtendedErrorCode: 0
  internalRequestId: 286068048
  merchantId: "4182997617632659388"
  merchantSiteId: "208906"
  orderId: "289210448"
  paymentOption: {
    userPaymentOptionId: "",
    …
  }
  reason: ""
  sessionToken: "f398e7d2-0f20-404b-9db5-95b9bf3c4c90"
  status: "SUCCESS"
  timeStamp: "20210621125321"
  transactionId: "1110000000015037030"
  transactionStatus: "APPROVED"
  transactionType: "Sale"
  userTokenId: "23081114722"
  version: "1.0"
}

3. 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:

You can use our Direct Merchant Notification (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
}

Alternatively, call the /getPaymentStatus API from your server side using the sessionToken (returned from the /openOrder and used in createPayment()).

Using the sessionToken retrieves the complete and verified payment response, including some additional information about the payment and card used for the transaction.

/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": "10",
    "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"
}

Payment Form (no Nuvei Fields)

When designing your payment page, you must prevent the customer from initiating the payment process twice, for example by pressing Submit 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.

1. Create the HTML Tags

Create the HTML Tags for the Web SDK Properties.

The following example SafeCharge.jsx code shows the creation of the HTML Tags for the Web SDK properties.

Example SafeCharge.jsx Code without Nuvei Fields

import React, { memo, useState } from "react";

export const SafeChargeCC = memo(({ safeCharge }) => {
  const [cardNumber, setCardNumber] = useState("");
  const [sessionToken, setSessionToken] = useState("");
  const [expDateMM, setExpDateMM] = useState("11");
  const [expDateYY, setExpDateYY] = useState("22");
  const [cardCVV, setCardCVV] = useState("");
  const [cardHN, setCardHN] = useState("CL-BRW1");

  const createPayment = (e) => {
    try {
      safeCharge.createPayment(
        {
          sessionToken: sessionToken,
          paymentOption: {
            card: {
              cardNumber: cardNumber,
              cardHolderName: cardHN,
              expirationMonth: expDateMM,
              expirationYear: expDateYY,
              CVV: cardCVV
            }
          },
          billingAddress: {
            email: "[email protected]",
            country: "GB"
          }
        },
        (resp) => console.log(resp)
      );
    } catch (e) {
      console.error(e);
    }
  };

  const authenticate3d = (e) => {
    try {
      safeCharge.authenticate3d(
        {
          sessionToken: sessionToken,
          paymentOption: {
            card: {
              cardNumber: cardNumber,
              cardHolderName: cardHN,
              expirationMonth: expDateMM,
              expirationYear: expDateYY,
              CVV: cardCVV
            }
          },
          billingAddress: {
            email: "[email protected]",
            country: "GB"
          }
        },
        (resp) => console.log(resp)
      );
    } catch (e) {
      console.error(e);
    }
  };

  return (
    <>
      <div className="container">
        <div className="item">
          <label htmlFor="sessionField">Session Token</label>
          <input
            id="sessionField"
            placeholder="Session Token"
            type="text"
            value={sessionToken}
            onChange={(e) => setSessionToken(e.target.value)}
          />
        </div>

        <div className="item">
          <label htmlFor="cardHolderName">Cardholder Name</label>
          <input
            id="cardHolderName"
            placeholder="Cardholder Name"
            type="text"
            value={cardHN}
            onChange={(e) => setCardHN(e.target.value)}
          />
        </div>

        <div className="item">
          <label htmlFor="card-number">Card number</label>
          <input
            id="card-number"
            placeholder="Card number"
            type="text"
            value={cardNumber}
            onChange={(e) => setCardNumber(e.target.value)}
          />
        </div>
        <div className="item">
          <label htmlFor="exp-dateMM">Expiration Date</label>
          <input
            className="exp-date"
            id="exp-dateMM"
            placeholder="MM"
            type="text"
            value={expDateMM}
            onChange={(e) => setExpDateMM(e.target.value)}
          />
          <input
            className="exp-date"
            id="exp-dateYY"
            placeholder="YY"
            type="text"
            value={expDateYY}
            onChange={(e) => setExpDateYY(e.target.value)}
          />
        </div>
        <div className="item">
          <label htmlFor="card-cvc">CVC</label>
          <input
            id="card-cvc"
            placeholder="CVC"
            type="text"
            value={cardCVV}
            onChange={(e) => setCardCVV(e.target.value)}
          />
        </div>
        <div className="item100 buttons">
          <button className="pay-button" onClick={createPayment}>
            Create Payment
          </button>

          <button className="pay-button" onClick={authenticate3d}>
            Authenticate3d
          </button>
        </div>
      </div>
    </>
  );
});

2. Sending a Request

You can send a createPayment() request to perform an end-to-end payment process.
Alternatively, you can perform a 3D-Secure authentication by calling the authenticate3d() method (which has the same input and output parameters as the createPayment() method).

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

Example `createPayment()` or `authenticate3d()` without Nuvei Fields

import React, { memo, useState } from "react";

export const SafeChargeCC = memo(({ safeCharge }) => {
  const [cardNumber, setCardNumber] = useState("");
  const [sessionToken, setSessionToken] = useState("");
  const [expDateMM, setExpDateMM] = useState("11");
  const [expDateYY, setExpDateYY] = useState("22");
  const [cardCVV, setCardCVV] = useState("");
  const [cardHN, setCardHN] = useState("CL-BRW1");

  const createPayment = (e) => {
    try {
      safeCharge.createPayment(
        {
          sessionToken: sessionToken,
          paymentOption: {
            card: {
              cardNumber: cardNumber,
              cardHolderName: cardHN,
              expirationMonth: expDateMM,
              expirationYear: expDateYY,
              CVV: cardCVV
            }
          },
          billingAddress: {
            email: "[email protected]",
            country: "GB"
          }
        },
        (resp) => console.log(resp)
      );
    } catch (e) {
      console.error(e);
    }
  };

  const authenticate3d = (e) => {
    try {
      safeCharge.authenticate3d(
        {
          sessionToken: sessionToken,
          paymentOption: {
            card: {
              cardNumber: cardNumber,
              cardHolderName: cardHN,
              expirationMonth: expDateMM,
              expirationYear: expDateYY,
              CVV: cardCVV
            }
          },
          billingAddress: {
            email: "[email protected]",
            country: "GB"
          }
        },
        (resp) => console.log(resp)
      );
    } catch (e) {
      console.error(e);
    }
  };


});

3. Response Verification

This step is the same as the Response Verification topic above.

Appendix

Get a Temporary Token

The getToken() method returns a temporary token (ccTempToken). This temporary one-time token is valid only for that API session, and is used only if you are processing with our server-to-server API and wish to be PCI descope.

Example `getToken()` Request

const getToken = (e) => {
  if (cardN) {
    try {
      safeCharge
        .getToken(cardN, {
          sessionToken: sessionToken,
          cardHolderName: cardHolderName,
          paymentOption: cardN,
          billingAddress: {
            email: "[email protected]",
            country: "GB"
          }
        })
        .then(function (result) {
          if (result.status === "SUCCESS") {
            console.log(result); //pass the paymentOption to the payment API call
          } else {
            console.log(result);
          }
        });
    } catch (e) {
      console.error(e);
    }
  }
};

Using ReactJS

Overview

Initiate a Session

Initialize Web SDK

Example App.js – Load and Initialized Web SDK and Set Safecharge Props

Example App.js – Add “safeChargeCC” Component and Pass safecharge as an HTML Prop

Payment Form with Nuvei Fields

1. Create the HTML Tags

Example SafeCharge.jsx Code

2. Sending the Request

Example createPayment() / authenticate3d() Request

Example createPayment() Response

3. Response Verification

Example /getPaymentStatus Request

Example /getPaymentStatus Response

Payment Form (no Nuvei Fields)

1. Create the HTML Tags

Example SafeCharge.jsx Code without Nuvei Fields

2. Sending a Request

Example createPayment() or authenticate3d() without Nuvei Fields

3. Response Verification

Appendix

Get a Temporary Token

Example getToken() Request

Example `createPayment()` / `authenticate3d()` Request

Example `createPayment()` Response

Example `/getPaymentStatus` Request

Example `/getPaymentStatus` Response

Example `createPayment()` or `authenticate3d()` without Nuvei Fields

Example `getToken()` Request