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 WordPress Plugin Store.

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 ‘manage_woocommerce’. Use the key as the username and the secret as the password to authenticate your requests.

When creating your headless store, 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 Simply Connect on a suitable page or in a suitable container as described in Nuvei documentation.

Getting Simply Connect Data

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

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

Example Request Input Parameters

{
    "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 must contain all information for the Simply Connect call.

Example Response with Simply Connect Information

{
    'sessionToken': the Nuvei order sessionToken, // will be used in updateOrder request
    'orderId': internal order ID, // will be used in updateOrder request
    'email': the billing email, // will be used in updateOrder request
    'transactionType': the request transaction type, // will be used in updateOrder request
    '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', // the html container ID who will hold the SimplyConnect output
    '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 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": { // custom data, do not pass it to the SimplyConnect. It will be used later.
        "wc_subscr": true|false, # is the product with WC 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": {
	    "subtotal": "15.32",
            "subtotal_tax": 0,
            "shipping_total": "0",
            "shipping_tax": 0,
            "shipping_taxes": [],
            "discount_total": 0,
            "discount_tax": 0,
            "cart_contents_total": "15.32",
            "cart_contents_tax": 0,
            "cart_contents_taxes": [],
            "fee_total": "0",
            "fee_tax": 0,
            "fee_taxes": [],
            "total": "15.32",
            "total_tax": 0
	}
    }
}

Using Response Data

From the above response data, exclude the products_data block 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, allow the customer to try the payment again. In any other negative case, it is recommended to reload Simply Connect by repeating the procedure in Getting Simply Connect Data.

Saving Metadata to a WooCommerce Order

Using headless implementation gives the merchant an option to save the WooCommerce Order before the Nuvei Payment. It is important to save some of the above information as metadata since it is based on the product_data class in the example response. 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 ‘_wcSubscription‘ meta data field with the ‘true‘ value.
4. For approved transactions, Nuvei adds the following meta fields: _nuveiTrId with Transaction ID value and _nuveiTransactions where Nuvei stores the main data for each transaction as separate classes. At this point, “_nuveiTransactions” holds only an empty block that is filled when the first DMN is received:

   {
     "{transaction_id}": {}
   }

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, 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.