VibeFox Nexi XPay for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active.

PHP: 8.0 or later.

Currency: the store or order currency must be EUR. 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 notification address is sent with every payment.

Public site: the notification URL must be reachable from the internet, with no maintenance mode, basic authentication or firewall rule blocking Nexi. Otherwise the payment is still confirmed by the signed customer return.

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

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_nexi_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Nexi XPay > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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

6. Turn on Enable/Disable and make a test order. When everything works, enter the live alias and MAC key and untick Test Mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Nexi XPay. Above the fields 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, and warns you when the gateway is enabled but the alias or MAC key of the current mode is empty, or when the store currency is not EUR. In both cases the payment method is hidden at checkout. Spaces and line breaks around pasted keys are removed when you save.

General

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. Default: Credit Card (Nexi). In test mode the checkout adds (TEST MODE) to the title.

Description: the payment method description displayed to the customer at checkout. Default: Pay securely with your credit card via Nexi XPay.

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

Test Mode: Enable test mode uses the Nexi XPay test environment and the test credentials. Untick it to take real payments with the live credentials. Default: on.

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.

Payment

The notification URL is sent to Nexi with every payment, so nothing has to be configured in the back office. The section shows it; it looks like https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}, with the order ID at the end. 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.

Immediate capture: the payment is captured at once and the order is marked as paid (default).

Deferred capture (authorize only): the capture follows your terminal profile. The order is put On hold as authorized until you capture it with the order action Capture Nexi XPay payment, or in the Nexi back office and then set the order to Processing.

Order Status After Payment: the status of the order after a successful payment. The status is set at once, with one status change and one e-mail.

Processing (WooCommerce default): the default.

Completed: every paid order becomes Completed.

On Hold: every paid order waits for your manual review.

Advanced

Debug Log: Enable logging logs payment events to WooCommerce > Status > Logs, source wcp_nexi_gateway. MAC keys, 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.

Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. Default: off.

Checkout

The customer chooses the payment method (by default Credit Card (Nexi)) and places the order. The next page shows Redirecting to Nexi XPay for payment... and sends the customer to the Nexi XPay page automatically, with a Pay Now button as a fallback. The payment is sent in EUR with a new transaction code, the customer's e-mail and the description Order, the order number and your site name. The Nexi page opens in the 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 the order received page of 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.

If the payment is declined, or the customer cancels on the Nexi page, they return to the checkout (or to the Pay for order page when the cart is empty) 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. Cancelling on the Nexi page leaves the order unchanged, so the customer can pay again.

If the plugin 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 payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

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

Orders and refunds

Order statuses

Pending payment: the customer was sent to Nexi and has not paid yet, or cancelled on the Nexi page.

Processing, Completed or On Hold: Nexi confirmed the payment. The status follows Order Status After Payment. The order note shows the authorization code, the transaction code, the card brand and the Nexi message. The transaction ID is the Nexi transaction code.

On hold (authorized): deferred capture is selected and the payment is only authorized. Capture it with the order action Capture Nexi XPay payment.

On hold (pending): Nexi reported the payment as pending confirmation. The order is updated by the final result.

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 order note explains it. Check the payment in the Nexi XPay back office and process or refund the order.

Failed: the latest payment attempt was declined, cancelled or ended with an error. The customer can pay again.

A paid order is never downgraded by a later failure. If another successful payment arrives for an order that is already paid, a note asks you to refund it in the Nexi XPay back office if it is a duplicate.

Deferred capture

For an authorized order on hold, open the order, choose Capture Nexi XPay payment in the order actions and click the arrow. The plugin captures the authorized amount in the environment of the payment and marks the order paid with the status from Order Status After Payment. If the capture fails, the error is shown on the order screen and added to the order notes, and the order stays on hold.

Refunds

Refunds are not made from WooCommerce, so there is no Refund via button. Make the refund in the Nexi XPay back office, then record it in WooCommerce manually.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Nexi XPay. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and deferred payments can still be captured.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store or order currency is EUR. The settings page shows a warning in these cases.

The payment went through, but the order stays Pending payment: 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 WooCommerce > Status > Logs, source wcp_nexi_gateway.

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: the transaction code was not issued by this store for that order. The result is ignored.

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

Order is On hold after payment: read the order note. Deferred capture is selected (capture the payment with the order action), the amount or currency did not match, a payment arrived for a cancelled order, the payment is pending at Nexi, or On Hold is selected as the status after payment.

Capture Nexi XPay payment is missing or fails: the action is shown only for Nexi orders that are on hold as authorized with deferred capture. If it fails, read the error in the order notes; the capture uses the keys of the environment the payment was made in.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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