VibeFox Nexi XPay for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Currency: the customer must check out in EUR, so the EUR currency must be enabled in System > Localisation > Currencies. For other currencies the payment method is hidden at checkout.

Nexi XPay account: you need a Nexi XPay merchant account ("Pagamento Semplice" redirect integration) with the alias (terminal ID) and the MAC key of your terminal. Test and live credentials are separate: test credentials come from the Nexi XPay test area or the developer portal (developer.nexi.it), live credentials from your Nexi XPay back office after the merchant account is activated. Nothing has to be set up in the Nexi back office: the return and notification addresses are sent with every payment.

Public store: the notification URL must be reachable from the internet, with no basic authentication or firewall rule blocking Nexi. If the notification cannot reach the store, the payment is still confirmed by the signed customer return.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_nexi_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_nexi_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_nexi_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Nexi XPay Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the page and click Activate (see License key).

4. Keep Test Mode on and enter the test alias and MAC key (see Configuration).

5. Turn on Enable/Disable, click Save and make a test order in EUR. When everything works, enter the live alias and MAC key and turn off Test Mode.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_nexi_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Nexi XPay Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the aliases and the MAC keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Notification URL).

A new install starts with the payment method turned off and test mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page shows Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. while test mode is on. It warns you when the gateway is enabled but the alias or MAC key of the current mode is empty (the payment method is then hidden at checkout), and when the default currency of the store is not EUR (the payment method is then shown only to customers who check out in EUR). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be longer than 128 characters, Sort Order must be a whole number, Total a number of 0 or more, and the geo zone and order statuses must exist; if any of these is wrong, nothing is saved. Spaces around pasted aliases and keys are removed.

Nexi XPay

Enable/Disable: Enable Nexi XPay Gateway turns the payment method on or off. Default: off.

Title: the payment method title displayed to the customer at checkout. It is also the payment method name stored in the order. Default: Credit Card (Nexi); an empty title uses the default. Up to 128 characters. In test mode the checkout and the order add (TEST MODE) to the title; a very long title is shortened so that the name with (TEST MODE) fits the 128 characters of the order.

Description: the text shown to the customer at the Confirm Order step. Default: Pay securely with your credit card via Nexi XPay.

Sort Order: the position of Nexi XPay among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Nexi XPay only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Nexi XPay is offered. Leave it empty to offer it for any total.

Test environment

Test payments go to int-ecommerce.nexi.it and never charge real cards. Get the test alias and MAC key in the Nexi XPay test area or the developer portal (developer.nexi.it, linked in the section).

Test Mode: uses the Nexi XPay test environment and the test credentials. Turn it off to take real payments with the live credentials. Default: on. While it is on, customers see TEST MODE: the payment goes to the Nexi XPay test environment, no real money is charged. at the Confirm Order step.

Test Alias: the alias (terminal ID) of your Nexi XPay test terminal.

Test MAC Key: the MAC calculation key of your Nexi XPay test terminal.

Live environment

The live alias and MAC key are shown in your Nexi XPay back office (ecommerce.nexi.it) after your merchant account is activated.

Live Alias: the alias (terminal ID) of your live Nexi XPay terminal.

Live MAC Key: the MAC calculation key of your live Nexi XPay terminal.

Saved MAC keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. To remove a saved key, tick Clear the saved MAC key on save under the field and click Save.

Payment

Notification URL: shown for reference. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_nexi_gateway/s2s&nexi_order={order_id}, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_nexi_gateway/payment/wcp_nexi_gateway.s2s&nexi_order={order_id}, with the order number at the end, and is built from the storefront address of your OpenCart installation. It is sent to Nexi with every payment, so nothing has to be configured in the Nexi back office. Nexi sends the payment result to this URL server-to-server and also passes it with the customer's return. Both are signed the same way and are checked with the MAC key of the environment the payment was made in, the alias of that environment and the transaction code issued for that order. Results that fail the check are rejected and change nothing.

Capture: when the money is taken.

Order Status After Payment: the status of the order after a successful payment. The OpenCart statuses used for each choice are set in the Orders section.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only from a verified Nexi result. Each field below lists your OpenCart order statuses. OpenCart has no On hold status: by default Pending is used and an order note explains why. You can create your own statuses in System > Localisation > Order Statuses and select them here.

Status: Processing: used when Order Status After Payment is Processing. Default: Processing.

Status: Completed: used when Order Status After Payment is Completed. Default: Complete.

Status: awaiting payment: Nexi reports the payment as pending (esito PEN). Default: Pending.

Status: on hold: amount or currency mismatch, a payment received for a cancelled order, deferred capture (authorized, not captured yet), or Order Status After Payment set to On hold. Default: Pending.

Status: payment failed: a pending payment that then failed. Default: Failed.

Status of cancelled orders: the status your store uses for cancelled orders. A payment received for such an order is put on hold, never marked as paid. The extension only reads this status and never sets it. Default: Canceled.

Advanced

Debug Log: logs payment events to nexi_ip_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. MAC keys, MACs, card data and e-mail addresses are not logged. Errors and warnings, for example a failed MAC check, are always logged, even when the option is off. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete Data on Uninstall: when on, uninstalling the extension removes the gateway settings and the log. The Nexi XPay payment records of orders are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The MAC keys are not exported.

Import: paste exported JSON and click Import to restore the settings. The saved MAC keys are not changed.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit Card (Nexi)). On OpenCart 4 the customer picks it with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. At the Confirm Order step the customer sees your description. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the page shows Redirecting to the Nexi XPay payment page... and Please do not close this window. and sends the customer to the Nexi XPay page automatically after a second, with a Pay with Nexi XPay button as a fallback. The payment is sent in EUR for the order total with a new transaction code, the customer's e-mail and the description Order, the order number and your store name. The Nexi page opens in the customer's store language when it is Italian, English, Spanish, French, German, Japanese, Chinese, Arabic, Russian or Portuguese, otherwise in English.

The customer pays and returns to your store. The order is marked paid only after a verified Nexi result with the exact order amount and currency: from the server-to-server notification or from the signed customer return, whichever arrives first. The order then gets its status the standard OpenCart way, with the usual order e-mail and stock update, and the customer sees the OpenCart order success page with Your Nexi XPay payment has been received. If Nexi reports the payment as pending, the page shows Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. For an order on hold (deferred capture or manual review) it shows Your Nexi XPay payment has been received and is being reviewed. We will contact you if anything is needed.

If the result has not been processed yet when the customer comes back, a Payment confirmation page shows We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. with a Check again button. The notification sets the order status as soon as it arrives.

If the payment is declined, a pending payment fails, or the customer cancels on the Nexi page, they return to the checkout and see one of these messages: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. or We could not confirm the payment. If your card was charged, please contact us before paying again. On OpenCart 4 these messages are shown above the checkout page. An order without a status stays without one and the cart is kept, so the customer can pay again. OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 keeps one order for the checkout and pays the same order again with a new transaction code. When another order of the same cart is already paid, awaiting payment or on hold, the customer goes to the success page instead of a new payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example a pending payment failed, or you cancelled it), the customer is sent back to the checkout with Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., also when the customer returns from Nexi, and the next Confirm Order pays a new order. If the order was paid and then closed by the store (for example refunded), the message is Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. If the order of the checkout is already placed and the cart has changed since, the message is Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

If the extension is not set up for the current mode, the customer sees This payment method is not available right now. Please choose another payment method.

The notification also works while the store is in maintenance mode, because OpenCart 3 lets payment extension requests through and on OpenCart 4 the extension adds a startup action for it, which also lets the customer return from Nexi.

The extension takes payments on the Nexi XPay page only. It has no refunds from OpenCart, no saved cards or OneClick, no subscriptions or recurring payments, no Pay-By-Link, no XPay Build embedded fields and no choice of payment methods in OpenCart: the Nexi page shows the methods enabled on your terminal.

Orders and refunds

Order statuses

No status (missing order): the customer was sent to Nexi and has not paid, cancelled or was declined, or Nexi has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Status: Processing, Completed or on hold: Nexi confirmed the payment. The status follows Order Status After Payment. A note shows the authorization code, the transaction code, the card brand and the Nexi message.

Status: on hold (authorized): deferred capture is selected and the payment is only authorized. Capture it with Capture Nexi XPay payment in the order tab.

Status: awaiting payment: Nexi reported the payment as pending confirmation. The order is updated by the final result.

Status: on hold after payment: the amount or currency received from Nexi did not match the order (the order is not marked paid), or a successful payment arrived for an order that had already been cancelled. The note explains it. Check the payment in the Nexi XPay back office and process or refund the order.

Status: payment failed: a pending payment failed.

A paid order is never downgraded by a later failure. If another successful payment arrives for an order that is already paid, or for another order of the same cart, a note on the paid order asks you to refund it in the Nexi XPay back office if it is a duplicate; the second order is not marked paid. When a pending payment later succeeds or fails, OpenCart notifies the customer of the new status.

Notes are entries in the order History that the customer does not see.

VibeFox Nexi XPay Gateway tab

In Sales > Orders open an order paid with Nexi XPay. At the bottom of the order page, next to History and Additional, the VibeFox Nexi XPay Gateway tab shows the transaction code (codTrans) with a Test environment label for test payments, the status and Nexi result, the capture mode and state, the amount sent to Nexi and the amount received, the authorization code, the card brand, the Nexi message, the date and the Nexi XPay notes of the order. The tab is shown to users who have access to the extension.

Deferred capture

For an authorized order on hold, click Capture Nexi XPay payment in the tab (the button shows the amount) and confirm the question Capture the authorized amount through Nexi XPay? You need the right to modify the extension (set in System > Users > User Groups). The extension captures the authorized amount in the environment of the payment, with that environment's keys, and sets the status from Order Status After Payment with a note. The status is changed directly, like a manual status change, without e-mails and stock movements. If the capture fails, the tab shows the error, a note is added and the order stays on hold. A second capture of the same payment is refused.

Refunds

Refunds are not made from OpenCart, so there is no refund button for Nexi XPay. Make the refund in the Nexi XPay back office, then record it in OpenCart manually. Product returns in Sales > Returns do not send money back through Nexi.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Nexi XPay Gateway is the first block on Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: opencart-payment-nexi and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Nexi XPay is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and authorized payments can still be captured.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

Nexi XPay does not appear at checkout: check that the license is active, Enable/Disable is on, the current mode has both credentials (Test Alias and Test MAC Key in test mode, Live Alias and Live MAC Key in live mode) and the customer checks out in EUR. The settings page shows a warning in these cases. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: neither the notification nor the customer return was accepted. Check that the store is reachable from the internet, that the MAC key and alias match the environment (test or live) of the payment, and turn on Debug Log to see what Nexi sent in the Log field on the extension page.

Notification answers invalid_mac or invalid_alias: the MAC key or the alias in the settings does not match the terminal that sent the result. Copy them again from the Nexi test area or back office.

Notification answers unknown_transaction or order_not_found: the transaction code was not issued by this store for that order, or the order does not exist. The result is ignored.

Notification answers not_configured or busy: the alias or MAC key of the payment's environment is empty, or the order was being updated by another request at the same moment. Nexi retries the notification.

The notification URL shows method_not_allowed in the browser: this is normal. The URL accepts only requests from Nexi.

The customer sees This payment method is not available. Please reload the checkout page.: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

Order is in the on-hold status after payment: read the Nexi XPay notes in the order tab. Deferred capture is selected (capture the payment with the button), the amount or currency did not match, a payment arrived for a cancelled order, or Order Status After Payment is set to On hold.

Capture Nexi XPay payment is missing or fails: the button is shown only for Nexi XPay orders that are on hold as authorized with deferred capture, and only to users who may modify the extension. If the alias or MAC key of the payment's environment is empty, the tab says so. If the capture fails, read the error in the tab and in the notes, for example Nexi XPay refused the capture with the Nexi code and message.

Test payments do not confirm a live payment: each payment is checked with the keys of the environment it was started in. Switch Test Mode to the mode you want and use that mode's alias and MAC key.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Nexi XPay Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the notification through in maintenance mode). If Delete Data on Uninstall is on, the other gateway settings (title, description, test mode, aliases, MAC keys, capture, order status after payment, debug log) and the log are removed. If it is off, they are kept for a later re-install. The Nexi XPay payment records of orders are always kept, so authorized payments can still be captured after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Nexi XPay Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Nexi and XPay are trademarks of their respective owners. This extension is not affiliated with or endorsed by Nexi.