• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Checkout Examples
      • Server-to-Server
      • Payment Scenarios
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Flow Diagrams
      • Plugins
        • Magento
          • Rebilling with Magento
        • WooCommerce
          • Rebilling with WooCommerce
        • PrestaShop
          • PrestaShop with Web SDK
          • PrestaShop with Checkout
        • OpenCart
        • Shopify (via AsiaBill)
        • Mirakl
        • Salesforce
        • SAP
        • WIX
      • Marketplaces
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion (DCC and MCP)
        • Payout
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscription (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
    • Guides
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APIs with Postman
        • Testing APMs
      • Response Handling
      • Alternative Payment Guides (APMs)
      • Airline Ticket Guides
        • Airline Addendum
        • External Authorization Addendum
      • Payment Facilitators (PayFac)
      • Cashier
        • Cashier Events Guide
        • Cashier Features
      • Withdrawal Guide
      • Risk Guide
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • Chargebacks
      • eKYC Guide
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
      • Fast Track Onboarding Developer Guide
      • Currency Conversion Guides
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Website Compliance Guides
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    Using ReactJS

    On this page:
    • Overview
    • Initiate a Session
    • Initialize Web SDK
    • Payment Form with Nuvei Fields
      • 1. Create the HTML Tags
      • 2. Sending the Request
      • 3. Response Verification
    • Payment Form (no Nuvei Fields)
      • 1. Create the HTML Tags
      • 2. Sending a Request
      • 3. Response Verification
    • Appendix
      • Get a Temporary Token

    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:

    1. Initiate a Session
    2. Initialize Web SDK
    3. 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 you 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:
      • Three-part Card Fields – Full Implementation
      • One-part Card Field – Full Implementation
      • Without Nuvei Fields – Full Implementation

      ReactJS Code – Sandbox Examples:

      You can try-out the sample Web SDK Flow ReactJS code in a sandbox:

      • Three-part Card Fields – ReactJS Sandbox
      • One-part Card Field – ReactJS Sandbox
      • Without Nuvei Fields – ReactJS Sandbox

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

    1. Create a ReactJS main app. (In our example we name it: "App.js".)
      (To see a full example, see the Example App.js topic.)
    2. 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.)
    3. 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"
              })
            );
          });
        }, []);
      
    4. 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 clicking the ‘Submit‘ button twice. Here are some suggestions:

    • Disable the button once it has been clicked.
    • 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 clicks the ‘Submit‘ button.

    1. 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: "someone@somedomain.com",
                  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: "someone@somedomain.com",
                  country: "GB"
                }
              },
              (resp) => console.log(resp)
            );
          } catch (e) {
            console.error(e);
          }
        }
      };
    2. 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.safecharge.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 clicking the ‘Submit‘ button twice. Here are some suggestions:

    • Disable the button once it has been clicked.
    • 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: "someone@somedomain.com",
                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: "someone@somedomain.com",
                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: "someone@somedomain.com",
                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: "someone@somedomain.com",
                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: "someone@somedomain.com",
                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);
        }
      }
    };

     

    2022 Nuvei. All rights reserved.