VibeFox Nexi XPay for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Currency: the cart 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 basic authentication or firewall rule blocking Nexi. The maintenance mode of the shop does not block it. If the notification cannot reach the shop, 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Nexi XPay Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure 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. When everything works, enter the live alias and MAC key and turn off Test Mode.

On install the module creates two order statuses, Awaiting Nexi XPay payment and Nexi XPay payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences. A country enabled in the shop after the module was installed must also be ticked there.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. Each section has its own Save button, which saves the whole page. 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. It warns you when the gateway is enabled but the alias or MAC key of the current mode is empty, or when the default currency of the shop is not EUR. In these cases the payment method is hidden at checkout. Spaces and line breaks around pasted values are removed when you save.

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). In test mode the checkout and the order add (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: uses the Nexi XPay test environment and the test credentials. Turn it off 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.

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.

Clear saved secrets: tick Test MAC Key or Live MAC Key and click Save to remove a saved key. An empty field keeps the saved value.

Payment

Notification URL: shown for reference. It is sent to Nexi with every payment, so nothing has to be configured in the Nexi back office. With friendly URLs it looks like https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, possibly with a language code such as /it/, and with the cart number 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 cart. 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 in Nexi XPay payment on hold as authorized until you capture it with Capture Nexi XPay payment on the order page, or in the Nexi back office and then set the order to Payment accepted.

Order Status After Payment: the status of the order after a successful payment.

Payment accepted (default): the standard PrestaShop status for paid orders.

Delivered (WooCommerce "Completed"): every paid order becomes Delivered.

Nexi XPay payment on hold: every paid order waits for your manual review. The payment is still recorded on the order.

Advanced

Debug Log: logs payment events to logs/nexi_ip_debug.log.php in the module folder. 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 module removes all module settings and the log. The Nexi XPay payment data of orders and the order statuses are kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Credit Card (Nexi)) and confirms. 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 for the cart total with a new transaction code, the customer's e-mail and the description Cart, the cart number and your shop name. The Nexi page opens in the cart language when it is Italian, English, Spanish, French, German, Japanese, Chinese, Arabic, Russian or Portuguese, otherwise in English. No order exists yet at this point.

The customer pays and returns to your shop. The order is marked paid only after a verified Nexi result with the exact cart amount and currency: from the server-to-server notification or from the signed customer return, whichever arrives first. The order is then created and the customer sees the standard order confirmation 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 We have received your Nexi XPay payment authorization. Your order will be processed shortly. If a pending payment later fails, the page shows The payment was not completed. Please contact us.

If the result has not been processed yet when the customer comes back, a 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 creates the order as soon as it arrives.

If the payment is declined, 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. No order is created and the cart is kept, so the customer can pay again. If the cart already has an order (for example, it was paid in another tab), the customer goes to the order confirmation instead of a new payment.

If the module 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 works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module takes payments on the Nexi XPay page only. It has no refunds from PrestaShop, 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 PrestaShop: the Nexi page shows the methods enabled on your terminal.

Orders and refunds

Order statuses

No order yet: the customer was sent to Nexi and has not paid, cancelled or was declined, or Nexi has not confirmed the payment yet. Only the cart exists.

Payment accepted, Delivered or Nexi XPay payment on hold: Nexi confirmed the payment. The status follows Order Status After Payment. The payment is recorded with the Nexi transaction code as the transaction ID, and a note shows the authorization code, the transaction code, the card brand and the Nexi message.

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

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

Nexi XPay payment on hold after payment: the amount or currency received from Nexi did not match the cart (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.

Payment error: a pending payment failed. The same cart cannot be paid again, so the customer has to place a new order.

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.

Nexi XPay payment block

The order page shows a Nexi XPay payment block with the transaction code (codTrans), the status and Nexi result, the capture mode, the amount sent to Nexi and the amount received, the authorization code, the card brand, the Nexi message and the date, a Test environment badge for test payments and the Nexi XPay notes of the order.

Deferred capture

For an authorized order on hold, click Capture Nexi XPay payment in the block (the button shows the amount) and confirm the question Capture the authorized amount through Nexi XPay? You need the right to edit orders. The module captures the authorized amount in the environment of the payment, with that environment's keys, records the payment and sets the status from Order Status After Payment. If the capture fails, the block 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 PrestaShop, so there is no refund button for Nexi XPay. Make the refund in the Nexi XPay back office, then record it in PrestaShop manually. The standard PrestaShop refund buttons of the order page do not send money back through Nexi.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Nexi XPay Gateway is the first block on Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-nexi and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and authorized payments can still be captured.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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 cart currency is EUR. The settings page shows a warning in these cases. In Payment > Preferences check that the module is allowed for EUR, the customer's country and the customer's group.

The payment went through, but no order was created: neither the notification nor the customer return was accepted. Check that the shop 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 module 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: the transaction code was not issued by this shop for that cart. 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, or the order could not be created (for example, the module is disabled). Nexi retries the notification.

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

Order is Nexi XPay payment on hold after payment: read the Nexi XPay notes in the order block. 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 Nexi XPay payment on hold is selected as the status after payment.

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 employees who may edit orders. If the alias or MAC key of the payment's environment is empty, the block says so. If the capture fails, read the error in the block 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 Modules > Module Manager, open the menu next to VibeFox Nexi XPay Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete Data on Uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Nexi XPay payment data of orders and the order statuses Awaiting Nexi XPay payment and Nexi XPay payment on hold are always kept, so authorized payments can still be captured after a re-install. Existing orders keep their payment notes and transaction IDs.

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