Overview

Since version 3.0.0, the Nuvei Checkout plugin for Magento 2 supports headless front-end store implementations via provided REST API endpoints.

The merchant needs to install and configure the Nuvei Checkout plugin for Magento 2, which can be downloaded from the Nuvei GitHub repository here.

After the plugin setup, the Nuvei gateway is available as a payment option.

The merchant needs access token for the requests.

To use the Integration token and enable OAuth access in your system, follow these steps:

1. Go to System > Integrations and create a new integration.
2. In the integration settings, go to the API section and select “Nuvei Checkout data” as the API you want to integrate with.
3. Save the integration settings.
4. Go to Stores > Configuration > Services > OAuth > Consumer Settings.
5. In the Consumer Settings section, find the option “Allow OAuth Access Tokens to be used as standalone Bearer tokens” and set it to Yes.
6. Save the configuration settings.

After saving the configuration, the merchant needs to create a store. During this process, the merchant should take into consideration the following behaviors related to the usage of the plugin:

• UPOs are not allowed for guest users.
• Guest users cannot shop products with Nuvei Payment plan.
• Finishing an order with mixed products (with and without Nuvei Payment plan) is not allowed. However, the client can buy more than one product with the same Nuvei Payment plan type.
• When the client buys a product with Nuvei Payment plan, only Credit Card payment options are allowed.

For more information, please refer to the main plugin page.

After completing the necessary steps, you can start using the Nuvei plugin REST API. The client can proceed with payment following below scenarios.

Using Nuvei Web SDK (Fields)

In this case, the merchant has to implement the Web SDK on their desired page or container as described in the Nuvei documentation.

To complete the payment, processing a quote with all payment information is a must. The merchant has to obtain Nuvei data to complete the process.

Getting Web SDK Parameters

To get those parameters, create a POST request to the following URL with below mentioned parameters in JSON format.

magento_domain/rest/V1/nuvei/get-checkout-data/{used_cart_id}/get-web-sdk-data/

{
'isUserLogged': 1 or 0
}

The response JSON data has to contain all the needed information for the Web SDK call.

{
  'sessionToken: the Nuvei order sessionToken,
  'total': the Base total from the Quote,
  'apms': 'list with available payment options',
  'upos': list with available UPOs, if any,
  'countryId': the country ID code,
  'useUPOs': the same setting from the plugin,
  // for the Web SDK
  'merchantSiteId': the parameter from the plugin settings,
  'merchantId': the parameter from the plugin settings,
  'isTestMode': the parameter from the plugin settings,
  'locale': ISO 2 code,
  'webMasterId': a plugin parameter,
  'sourceApplication': a plugin parameter,
  'userTokenId': It is the email of the client if they are logged in,
  'currencyCode': ISO 3 code from the Quote,
}

If the client completes the payment with a credit card or direct APM, the SDK returns the transaction status and transaction ID. the front-end has to redirect the client to one of the complete pages.

Getting an APM Redirect URL

In case of using redirect APM, the front-end has to obtain it by calling another plugin endpoint.

magento_domain/rest/V1/nuvei/get-checkout-data/{used_cart_id}/get-apm-redirect-url/

Call the plugin endpoint with a POST request and pass a JSON with the following parameters:

{
  'chosenApmMethod': the APM parameter from the above response,

  //The following fields, if they exist, are specific mandatory APM fields. The merchant has to collect them on the checkout page.

  'apmMethodFields': {
    'apmField1_name': value of the input,
    'apmField2_name': value of the input,
    ...
    }
  'savePm': 1 or 0 according to client desire to save the method as UPO,
  'urlDetails': {// Used for redirect APMs
    'successUrl': the success page after approved order
    'failureUrl': the failure page after failed order
    'pendingUrl': the pending page after pending order (in most cases it is same as success page)
    'backUrl': usually this is the Cart page, client can return here after redirect to some APM page and click on Cancel button.
  },
}

If there are no errors, the redirect URL is returned as JSON:

{
redirectUrl: a URL to redirect.
}

We recommend that the merchant implements a request to the /updateOrder endpoint when the client presses the Pay button. By making this call, the merchant ensures that the latest information from the quote is sent to the Nuvei system. This helps prevent any divergence between the Nuvei Order total and the quote total, especially in situations where the client has multiple tabs with checkout pages opened.

Using Simply Connect (Checkout SDK)

In this case, the merchant has to implement the Simply Connect on their desired page or container, following the instructions provided in the Nuvei documentation

To complete the payment process, a quote with all payment information is a must. The merchant has to obtain Nuvei data to complete the process.

Getting Simply Connect Parameters

To get those parameters, create a POST request to the following URL with below parameter in JSON format:

magento_domain/rest/V1/nuvei/get-checkout-data/{used_cart_id}/ get-simply-connect-data/

{
redirectUrl: a URL to redirect.
}

The response JSON data has to contain all needed information for the Simply Connect call:

{
  'sessionToken': the Nuvei order sessionToken,
  'isTestMode': the parameter from the plugin settings,
  'countryId': the country ID code,
  'isPaymentPlan': information about a product with Nuvei Payment plan,
  'nuveiCheckoutParams': {
  '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 holds the Simply Connect 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's full name by Billing Address,
  'email': the billing email,
  '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)
}

After the payment process is complete, the SDK provides the transaction status and transaction ID. Subsequently, the front-end needs to redirect the client to one of the completion pages.

We recommend that the merchant implement a request to the /updateOrder endpoint when the client presses the Pay button. With this call, the merchant ensures that the latest information from the quote is sent to the Nuvei system, preventing any divergence between the Nuvei Order total and the quote total in the case when more than one tab with the checkout page is opened.

You also need to check the prePayment and onResult eventsof Simply Connect. The prePayment event can be used for updating the order or checking if “Terms and Conditions” are applied.

The onResult  method is used to get the response from the Simply Connect call and can be utilized for redirecting to the success page. These methods provide additional functionality to manage the payment process and handle the responses from Simply Connect effectively.

In the event of an error following any of the requests, the expected data is absent, and an error message is generated:

{
'message': some error message
}

Updating a Nuvei Order

To initiate order update, create a POST request to the following endpoint without parameters:

magento_domain/rest/V1/nuvei/get-checkout-data/{used_cart_id}/update-order/

As a result, a sessionToken is returned:

{
sessionToken: same token or new one, if the old is expired.
}

The Session Token remains the same if the update is successful or if it results in the creation of a new order in the Nuvei system. However, if the Session Token is different than the previous one, the Web SDK must be called using the new token.

In the event of an error following any of the requests, the expected data is absent, and an error message is generated:

{
'message': some error message
}