Introduction

Beginning with version 2.0.0, the Nuvei Checkout plugin for WooCommerce supports headless front-end store implementations via provided REST API endpoints.

The merchant must install and configure the Nuvei Checkout plugin for WooCommerce, which can be downloaded from the Nuvei GitHub repository here.

After the plugin is set up, the Nuvei gateway has to be available as a payment option.

You also need the following:

• A working Base Authentication for the site
• WooCommerce REST API consumer key and secret with read/write permissions for an admin level user, or at least a user who can “activate_plugins”. Use the key as the username and the secret as the password to authenticate your requests.

If you are not familiar with creating WooCommerce REST API keys, please refer to WooCommerce documentation.

When creating your headless store, please use the plugin as it is used in a normal WooCommerce  store; call the SDK after you collect and validate the Billing and the shipping addresses, Cart/Order total, and the currency!

Using Simply Connect (Checkout SDK)

In this case, the merchant has to implement the Simply Connect in its desired page or container as described in Nuvei documentation.

Getting Simply Connect Data

To obtain Simply Connect data, the front-end has to provide a WooCommerce Cart, obtained from the WooCommerce Store API, or cart-like information to the plugin sending POST request to:

wc_admin_domain/wp-json/wc/nuvei/?action=get-simply-connect-data

Example Request

{
    "shipping_address": {
        "first_name": "name",
        "last_name": "name",
        "company": "",
        "address_1": "address",
        "address_2": "",
        "city": "city",
        "state": "ST",
        "postcode": "64283",
        "country": "DE",
        "phone": "123456"
    },
    "billing_address": {
        "first_name": " name",
        "last_name": " name",
        "company": "",
        "address_1": " address",
        "address_2": "",
        "city": " city",
        "state": "ST",
        "postcode": "64283",
        "country": "DE",
        "email": "[email protected]",
        "phone": "123456"
    },
    "items": [
        {
            "key": "c74d97b01eae257e44aa9d5bade97baf",
            "id": 16,
            "quantity": 1,
            "variation": [],
            "item_data": []
        }
    ],
    "totals": {
        "total_items": "2500",
        "total_items_tax": "0",
        "total_fees": "0",
        "total_fees_tax": "0",
        "total_discount": "0",
        "total_discount_tax": "0",
        "total_shipping": "200",
        "total_shipping_tax": "0",
        "total_price": "2700",
        "total_tax": "0",
        "tax_lines": [],
        "currency_code": "EUR",
        "currency_symbol": "€",
        "currency_minor_unit": 2,
        "currency_decimal_separator": ".",
        "currency_thousand_separator": ",",
        "currency_prefix": "€",
        "currency_suffix": ""
    },
    "isUserLogged": "" // 1 or 0 # custom parameter to know if the user is logged in the shop
}

The response JSON data have to contain all information for the Simply Connect call.

Example Response

{
  "sessionToken":"the Nuvei order sessionToken",
  "orderId":"internal order ID",
  "email":"the billing email",
  "transactionType":"the request transaction type",
  "env":"test or prod",
  "merchantId":"the merchant ID",
  "merchantSiteId":"the merchant Site ID",
  "country":ISO 2 country code,
  "currency":ISO 3 currency code,
  "amount":"the amount",
  "renderTo":"#nuvei_checkout",
  "useDCC":"use or not DCC (according to plugin settings)",
  "strict":false,
  "savePM":"save or not selected PM as UPO (depends on the plugin settings and""isPaymentPlan""parameter)",
  "showUserPaymentOptions":"show or not UPOs (according to plugin settings)",
  "alwaysCollectCvv":true,
  "fullName":"the client’s full name by Billing Address",
  "payButton":"the text on the Pay button (according to plugin settings)",
  "showResponseMessage":false,
  "locale":ISO 2 locale code,
  "autoOpenPM":1 or 0 (according to plugin settings),
  "logLevel":"SDK log level (according to plugin settings)",
  "maskCvv":true,
  "i18n":"SDK translation if any (according to plugin settings)",
  "blockCards":"list with blocked cards if any (according to plugin settings)",
  "pmWhiteList":"optional list with whitelisted PMs",
  "theme":"the SDL theme",
  "products_data":{
    ,
    "do not pass it to the Simply Connect. It will be used later.""wc_subscr":"true|false",
    "# is the product with WooCommerce Subscription or not""subscr_data":[
      "# the Nuvei subscription details if any"{
        "product_id":16,
        "planId":"3568",
        "recurringAmount":"3.99",
        "recurringPeriod":{
          "day":"3"
        },
        "startAfter":{
          "day":"0"
        },
        "endAfter":{
          "day":"4"
        },
        "item_id":"c74d97b01eae257e44aa9d5bade97baf"
      }
    ],
    "products_data":[
      {
        "product_id":16,
        "quantity":1,
        "price":"25",
        "name":"Beanie with Payment plan attribute",
        "in_stock":true,
        "item_id":"c74d97b01eae257e44aa9d5bade97baf"
      }
    ],
    "totals":"27.00"
  }
}

Using Response Data

From the above response data, exclude the products_data class and pass it to the Simply Connect call. After the client completes the payment, Simply Connect returns the transaction status and transaction ID in the onResult event.

In the case of a“declined” transaction, just allow the customer to try the payment again. In any other negative case, it is recommended to reload the Simply Connect (repeat Get Simply Connect Data).

Saving Metadata to an Order

Using headless implementation gives the merchant an option to save the WooCommerce Order before the Nuvei Payment. The important part is to save some of the above information as metadata! It is based on the product_data class from in the example response. Also, create the WooCommerce Order with status Pending, and allow the incoming DMN to change its status!

1. If there is a product with Nuvei Subscription as an attribute in the Order, a meta value must be saved with the following key: “_nuveiSubscr_product_{product_id}“.
2. If there is a product with Nuvei Subscription as variation into the Order, a meta value must be saved with the following key: “_nuveiSubscr _variation_{variation_id}“.
   In both cases, the value for the meta field is an array with the subscription data:

   {
     "product_id/variation_id":"the ID according case 1 or 2",
     "planId":"Nuvei plan ID",
     "recurringAmount":"the recurring amount",
     "recurringPeriod":{
       "day":"the recurring period"
     },
     "startAfter":{
       "day":"days count to start the recurring"
     },
     "endAfter":{
       "day":"days count to end after"
     },
     "item_id":"the item ID/item key, the string identification"
   }

3. If the Order contains WCS product, set the following meta field: _wcSubscription with value true.
4. For approved transactions, we add the following meta fields: _nuveiTrId with value the Transaction ID and _nuveiTransactions where we store the main data for each transaction as separate classes. At this point, “_nuveiTransactions” holds only an empty class that is filled when the first DMN arrives:

   {
     "{transaction_id}": {}
   }

Please check “prePayment” and “onResult” methods of Simply Connect. prePayment can be used for a final check of “Terms and Conditions” or to pass the latest Cart information to Nuvei system. onResult gets the response from the Simply Connect call and can be used for a redirect to a success page, or to get new Simply Connect data in case the session token expired.

Updating the Order

The /updateOrder request is almost the same as the request in point Get Simply Connect Data. Create a POST request to the following URL:

wc_admin_domain/wp-json/wc/nuvei/?action= get-simply-connect-data

The input parameters are same as in point Get Simply Connect Data. The plugin recognizes that this is an Update Order request by the additional parameters obtained from the very first call to the endpoint:

sessionToken
orderId
email
transactionType
products_data

In case the sessionToken in the response is the same as the one that is passed, just continue since the update was successful. In case it is different, reload Simply Connect with the data from the response.

If you do not receive a sessionToken, accept it as an error. More details for the error are saved in the plugin log.

Pre-payment Check

When the client presses the Simply Connect Pay button, it is the last place to check if the correct data was sent to Nuvei. To do this, just compare the last sent information to the endpoint from Get Simply Connect Data with the current information. If there are any changes, please create an /updateOrder request as described in Update the Order, then reload the Simply Connect!

Using the Cashier Redirect Link

To use a redirect link to our Cashier page, there must be a created order and you need its data. To get the link, you must create a GET request to:

wc_admin_domain/wp-json/wc/nuvei/?action= get-cashier-link

You should also pass the following parameters:

{
  "id":"the id of the Order",
  "successUrl":"URL where the Cashier will redirect after the payment",
  "backUrl":"back URL if the client cancel the payment, usually this is the Cart or Checkout page"
}

Expect a JSON response with the redirect link or an error message.