VibeFox Nexi XPay for Adobe Commerce — Help

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4.

Currency: the order currency must be EUR. For other currencies the payment method is hidden at checkout. If your base currency is not EUR, set EUR as the display currency of the store view or website where Nexi XPay is used.

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 URL 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. 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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-nexi-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/NexiPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_NexiPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Nexi XPay Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Keep Test Mode at Yes, enter the test alias and MAC key, set Enable Nexi XPay to Yes, click Save Config and place a test order in EUR. When everything works, enter the live alias and MAC key, set Test Mode to No and click Save Config.

The module adds the Credit Card (Nexi) payment method to the Magento checkout. It is off after installation (Enable Nexi XPay = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates one table for the Nexi XPay payment attempts.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Nexi XPay Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99". Spaces around pasted values are removed when you save.

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a title for the payment method (1 to 128 characters)., "Sort order" must be a whole number., "Minimum Order Total" must be a number, 0 or greater. or the same for Maximum Order Total.

While Enable Nexi XPay is Yes, the Notification URL and status row shows Nexi XPay: test mode is on. in test mode, Nexi XPay: alias or MAC key is missing. when a credential of the current mode is empty (the method is then hidden at checkout) and Nexi XPay: payment is available only for EUR orders. when the default currency is not EUR.

General

Enable Nexi XPay: shows or hides Nexi XPay at checkout. It is shown only when the alias and MAC key of the current mode are set and the order currency is EUR. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit Card (Nexi). Required, up to 128 characters. In test mode the checkout and the order add (TEST MODE) to the title.

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay securely with your credit card via Nexi XPay.

Sort order: the position among the payment methods at checkout. A whole number, including negative values.

Test and live credentials

Test Mode: sends payments to the Nexi XPay test environment (int-ecommerce.nexi.it) with the test credentials. No real cards are charged. Default: Yes. Set it to No to take real payments with the live credentials. While it is on, customers see Test mode: no real payment is taken. under the payment method.

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 Alias: the alias (terminal ID) of your live Nexi XPay terminal, from your Nexi XPay back office (ecommerce.nexi.it).

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

Magento stores the MAC keys encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config.

Results and captures are always checked with the alias and MAC key of the environment the payment was made in. A payment started in test mode is still verified with the test key after you switch to live.

Payment

Capture: when the money is taken.

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

Conditions

Payment from Applicable Countries: All Allowed Countries offers Nexi XPay for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Nexi XPay only for billing addresses in these countries.

Minimum Order Total: offer Nexi XPay only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Nexi XPay only up to this order total, in the base currency. Empty means no maximum.

Notification URL

Notification URL and status: shows, for reference, the notification URL of the default store view. It looks like https://your-store/wcpnexigateway/webhook/index/?nexi_order=ORDER_ID. Each payment sends this URL of the store view where the order was placed, with the order number instead of ORDER_ID, 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 and the alias of the environment the payment was made in, and with the transaction code issued for that order. Results that fail the check are rejected and change nothing.

Advanced

Debug Log: writes payment events to var/log/nexi_ip_debug.log.php in the Magento folder. The file cannot be opened from the web. MAC keys, signatures, tokens and e-mail addresses are not logged. Errors and warnings, for example a failed confirmation or an order e-mail that could not be sent, are always logged, even when the option is off. Default: No.

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

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Nexi XPay payment attempts, the orders and their history always stay. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Credit Card (Nexi)) and sees the description and the note You will be redirected to Nexi XPay to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The next page sends the customer to the Nexi XPay payment page automatically, with a Continue to Nexi XPay button as a fallback.

The payment is sent in EUR for the order total, with a new transaction code for every attempt, the customer's e-mail and the description Order, the order number and your store name. The Nexi page opens in the language of the store view when it is Italian, English, Spanish, French, German, Japanese, Chinese, Arabic, Russian or Portuguese, otherwise in English. Card data never touches your site.

The order is marked paid only after Nexi confirms it: by the server-to-server notification or by the signed customer return, whichever arrives first. The amount and currency must match the order. With immediate capture Magento then creates the invoice with the Nexi transaction code as the transaction ID, the order gets the status from Order Status After Payment and the order e-mail is sent. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page.

If the result has not arrived yet when the customer comes back, or Nexi reports the payment as pending, the customer is taken to the cart with Your payment is being confirmed. Please check again. The order waits in Pending Payment and is updated by the notification. If the payment needs your review (for example, the amount did not match), the customer sees Your Nexi XPay payment requires review.

If Nexi reports the payment as declined, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The payment was not completed. You can try again. If the customer cancels on the Nexi page, the cart is restored with The payment was cancelled. You can try again. This return is not signed by Nexi, so it does not change the order: it stays in Pending Payment, and a late Nexi result is still applied to it. If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees Nexi XPay payment could not be started. Please try another method. If the cart already has a paid, authorized, pending or held Nexi XPay payment, no second payment is started.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If Nexi later reports a payment for a cancelled order, the order is not invoiced: a note asks you to check the stock and the payment in the Nexi back office.

The module takes payments on the Nexi XPay page only. It has no online refunds from Magento, no saved cards or OneClick, no subscriptions or recurring payments, no Pay-By-Link, no XPay Build embedded fields and no partial capture. The Nexi page shows the payment methods enabled on your terminal. Nexi XPay is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Nexi, but no result has arrived yet, the customer cancelled on the Nexi page, or Nexi reported the payment as pending (note Nexi XPay payment is pending confirmation.). There is no invoice.

Processing, Complete or On Hold: Nexi confirmed the payment. The status follows Order Status After Payment. The invoice carries the Nexi transaction code as the transaction ID, and a note says Nexi XPay payment confirmed by s2s or return, with the transaction.

Processing (authorized, no invoice): deferred capture is selected and the payment is only authorized. The note says Nexi XPay authorized. Capture online using a native invoice. The order e-mail is sent after the capture.

On Hold after payment: the amount or currency received from Nexi did not match the order (note Nexi XPay amount/currency mismatch. Manual review required.), or a payment arrived for an order that was no longer waiting. No invoice is created. Check the payment in the Nexi back office and process or refund the order there.

Canceled: Nexi reported the payment as declined (note Nexi XPay payment was not completed.), the payment could not be started, or the order was cancelled in Magento.

A paid order is never changed by a later result, and repeated results never invoice an order twice. If a second payment arrives for the same cart, nothing is invoiced again and a note asks you to review it and refund it in the Nexi back office. The notes are order comments that the customer does not see.

Nexi XPay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Nexi XPay environment (test or live), Nexi XPay transaction, Authorization code and Captured transaction. It is shown also when the module is disabled. The customer sees only the payment method title.

Deferred capture

For an authorized order, click Invoice on the order page, choose Capture Online and click Submit Invoice. The module captures the authorized amount in the environment of the payment, with that environment's keys, and checks the signature of Nexi's answer. After the invoice is saved the order gets the status from Order Status After Payment, a note says Nexi XPay deferred capture completed. and the order e-mail is sent. The capture must be for the full order total, otherwise Magento shows Nexi XPay requires a full capture. If Nexi refuses the capture, Magento shows Nexi XPay capture failed: with the Nexi code and message, and the invoice is not created; you can try again. If the answer of Nexi was unclear (for example, no connection), the capture is not repeated automatically: Magento shows Capture outcome requires review in Nexi back office before retry. Check the payment in the Nexi back office. A second capture of the same payment is never sent.

Refunds

Refunds from Magento are not sent to Nexi. Refund the payment in the Nexi XPay back office, then create a credit memo for the invoice with Refund Offline to record the refund in Magento.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Nexi XPay Gateway is the first row of the VibeFox Nexi XPay Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-nexi and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees Nexi XPay payment could not be started. Please try another method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides 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 module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Nexi XPay does not appear at checkout: check that the license is active and Enable Nexi XPay is Yes for the website of the store, and that the current mode has both credentials: Test Alias and Test MAC Key in test mode, Live Alias and Live MAC Key in live mode. The Notification URL and status row shows a warning when one is missing. Check that the currency of the cart is EUR. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

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 and that the alias and MAC key match the environment (test or live) of the payment. Turn on Debug Log and read the Log field. If Nexi reported the payment as pending, the order waits until Nexi sends the final result.

The notification answers invalid_mac or invalid_alias (403): 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.

The notification answers unknown_transaction (400) or order_not_found (404): the transaction code or the order was not issued by this store. The result is ignored.

The notification answers not_configured or busy (503): 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 an error occurred while the order was being updated. Nexi retries the notification.

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

Results fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by the next result that reaches the store.

A payment was made but the order is On Hold or Canceled: read the order notes. The paid amount or currency did not match the order, the payment arrived after the order had been cancelled (for example by the Pending Payment Order Lifetime cron), or On Hold is selected in Order Status After Payment. Check the transaction in the Nexi back office.

The customer is back in the cart with Nexi XPay payment could not be started: the order currency is not EUR, the alias or MAC key of the current mode is empty, the module was disabled or the license is not active. The order of that attempt is cancelled.

The capture fails: read the message. Nexi XPay requires a full capture. means the invoice is not for the full order total. No Nexi XPay authorization to capture. means the order has no authorized Nexi payment. For Capture outcome requires review in Nexi back office before retry. check the payment in the Nexi back office; if it was captured there, create the invoice with Capture Offline.

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the Nexi XPay back office, then use Refund Offline.

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.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_NexiPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_NexiPayment to remove the data, then bin/magento module:disable Vibefox_NexiPayment, delete the folder app/code/Vibefox/NexiPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings, the module cache and the log are removed too. If it is No, the settings are kept for a re-install. The Nexi XPay payment attempts are always kept, so a late result of an old payment is still handled and authorized payments can still be captured after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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