VibeFox Nets Nexi 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, with the cURL and JSON extensions.

Nets account: you need the secret keys of your Nets Easy account (test and live). Only the secret keys are used. The checkout keys are not needed, because customers pay on the Nets hosted payment page. There is nothing to set up in the Nets portal for webhooks: the module registers them with every payment.

Currencies and payment methods: the module does not restrict currencies itself. The payment is made in the order currency, so use currencies enabled in your Nets account; an unsupported currency is reported by Nets when the payment is created. Which payment methods the customer sees on the Nets page depends on your Nets contract, country and currency.

HTTPS for webhooks: Nets only calls public HTTPS addresses of at most 256 characters without "&", so your storefront needs HTTPS to receive webhooks. Without them the payment is still confirmed when the customer returns to the store or with the status check on the order page.

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-nets-nexi-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/NetsNexiPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_NetsNexiPayment 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 Nets Nexi 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. Copy the test secret key from the Nets Easy test portal and paste it into Test Secret Key (see Configuration). Set Enable to Yes, keep Test mode at Yes, click Save Config and place a test order. Then enter the live secret key, set Test mode to No and click Save Config.

The module adds the Nets Easy payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Nets payment attempts, refunds and processed events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Nets Nexi 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; this module has no settings per store view. Delete settings on uninstall is read from the Default Config only. Save Config saves the whole page. The settings are one list; below they are grouped by topic in the order of the page.

If Title is empty or longer than 128 characters, Magento shows the error Enter a title of up to 128 characters. and nothing on the page is saved.

Payment setup

The Payment setup row at the top of the group shows notes for the current settings. When Enable is Yes and the secret key of the selected mode is missing, it shows Enter the secret key of the selected environment. The payment method is hidden until it is configured. When Enable is Yes and test mode is on, it shows Nets Easy is in TEST MODE. No real money will be charged. It always shows Webhooks require a public HTTPS URL of up to 256 characters without ampersands. Return and admin status checks work without webhooks. and the webhook address of your storefront (see Webhooks).

General

Enable: shows or hides Nets at checkout. It is shown only when the secret key of the selected mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Nets Easy. Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the title, when the customer selects Nets. HTML tags are removed. Default: Pay securely with Nets Easy.

API keys

Copy the secret keys from the Nets Easy portal under Company > Integration: the test portal (test.portal.dibspayment.eu) for the test key and the live portal (portal.dibspayment.eu) for the live key. The checkout keys are not needed.

Test mode: Yes uses test.api.dibspayment.eu with the test secret key; No uses api.dibspayment.eu with the live secret key. Captures, status checks and refunds of an order always use the environment in which it was paid. Default: Yes. While it is on, customers see TEST MODE: no real payment will be made. under the payment method.

Test Secret Key: your Nets test environment secret API key.

Clear saved test secret key: set to Yes and click Save Config to remove the saved test secret key. The switch goes back to No after saving.

Live Secret Key: your Nets live environment secret API key.

Clear saved live secret key: set to Yes and click Save Config to remove the saved live secret key.

Magento stores the keys encrypted and shows only a mask (******) after saving. Leave the mask as it is, or leave the field empty, to keep the saved key; type a new value to change it. An empty field does not delete the key: use the Clear saved … switch for that.

Orders

Order status after payment: the order status set once Nets has confirmed and charged the payment.

Payments that need your review always go to On Hold (see Order statuses).

Advanced

Debug log: when Yes, writes Nets requests and payment status changes to var/log/nng_debug.log.php in the Magento folder. Errors and warnings are always written. The file cannot be opened from the web and is rotated at 5 MB. Secret keys, e-mail addresses and card-like numbers are masked. Default: No.

Delete settings 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 Nets payment records always stay, so old orders can still be refunded. Default: No.

Conditions

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

Payment from specific countries: offer Nets only for billing addresses in these countries.

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

Maximum order total: offer Nets only up to this order total, in the base currency. Empty means no maximum.

Sort order: the position among the payment methods at checkout.

Debug log (the last row): shows the latest entries of the log. Click Clear log to empty it.

Webhooks

Nets notifications (webhooks) are registered automatically with every payment. There is nothing to configure in the Nets portal. They are sent to the storefront address of the store view of the order, which looks like https://your-store/wcpnetsnexigateway/webhook/index/; Payment setup shows this address for the default store view. If the address is not a public HTTPS address of at most 256 characters without "&", no webhooks are registered, and payments are confirmed when the customer returns to the store or with Nets: check payment status and capture on the order page. These events are registered:

Each webhook must carry the random secret that the module created for that payment. Webhooks without the correct secret are rejected. The webhook only tells the module which payment changed: the payment itself is always read from the Nets API with the secret key of the environment it was made in.

Checkout

At the payment step the customer chooses the payment method (by default Nets Easy) and sees the description. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Nets payment for the order total in the order currency, with the products, shipping and discounts as order lines, and sends the customer to the Nets hosted payment page. The customer's e-mail, name, address and phone number are passed to Nets when Nets accepts their format. The terms link on the Nets page opens your store home page.

After paying, the customer returns to your store. The order is marked paid only after Nets confirms it: the module reads the payment from the Nets API, compares the reserved amount and currency with the order, charges the reservation and only then creates the invoice. This happens on the webhook or when the customer comes back, whichever is first. Magento then creates the invoice with the Nets charge ID as the transaction ID, sets the status from Order status after payment and sends the order e-mail. The customer sees the standard order success page. If the payment is not confirmed yet, the success page shows Nets payment is awaiting confirmation. A customer who comes back in another browser lands on the home page with Nets payment status checked. Contact the store if needed.

If the customer cancels on the Nets page or the payment was not completed, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The Nets payment was not completed. On a new attempt the module first checks the previous Nets payment of the same cart. If it is already paid, that order is confirmed instead of a new payment; otherwise the previous Nets session is closed and its order is cancelled before a new payment starts.

If Nets refuses to start the payment, the order is cancelled, the cart is restored and the customer sees Nets Easy is temporarily unavailable. Please try again. in the cart. The details are written to the log. If the answer of Nets is uncertain (for example a timeout, or a previous session could not be closed), the order stays in Pending Payment and the customer sees a Payment confirmation page with a short message, for example The payment response is uncertain. Contact the store before retrying. or This payment is being checked. Please retry shortly., and the link Check again. Check such orders in the Nets portal.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its open Nets session is closed and can no longer be paid.

The module works with the standard Magento checkout and uses the Nets hosted payment page only. It has no embedded on-page Nets checkout, no subscriptions or recurring payments, no saved cards, no invoice fees, no authorize-only mode and no partial captures per shipment. Nets is not offered for orders created in the Admin or for checkout with multiple addresses.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Nets, but the payment is not confirmed yet. There is no invoice.

Processing or Complete: Nets confirmed and charged the payment. The status follows Order status after payment. The invoice is created with the Nets charge ID as the transaction ID, and a note shows the payment ID, the charge ID and the payment method.

On Hold: the amount or currency at Nets differs from the order, the capture was declined or its result is uncertain. No invoice is created and nothing is captured automatically. The note Nets payment requires review: with the reason asks you to verify the payment in the Nets portal. After reviewing the order, capture it with Nets: check payment status and capture, or cancel the reservation in the Nets portal.

Canceled: the customer cancelled or did not complete the payment, the payment could not be started, the reservation was cancelled at Nets, or the order was cancelled in Magento. If a payment arrives for a cancelled order, the order stays Canceled with a review note; capture or cancel the reservation, or refund a charged payment, in the Nets portal.

Closed: the payment was fully refunded with a credit memo.

Repeated webhooks and reloads never charge twice or create a second invoice. If a second payment arrives for an order that is already paid, the order is not changed: a reserved duplicate is released automatically, and a note asks you to verify it or to refund a charged duplicate in the Nets portal. The notes are order comments that the customer does not see.

Nets payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Nets payment ID and Nets charge ID. The customer sees only the payment method title. On the Information tab the block Nets payment history lists every Nets payment attempt of the order with the payment ID, charge ID, mode, status, review reason, amount in minor units and currency.

Nets: check payment status and capture: a button in the block for orders that are not paid and not cancelled, shown to Admin users who may edit orders. It reads the payment from Nets and captures a reservation that matches the order, also after a failed capture or after you have reviewed an order on hold. The result is shown as a message, for example Payment charged, Held for review or Payment not reserved.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Nets to the charge of the order, in the environment in which it was paid. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Nets.

The refund amount is the credit memo total in the order currency. If Nets does not accept the refund, Magento shows the error, for example Nets refund failed. Verify its status in Nets portal before retrying., and the credit memo is not created. After a successful refund Magento records it with the Nets refund ID as the transaction ID. A full refund closes the order. Refunds are available once the payment has been charged and the order has an invoice.

Refunds made in the Nets portal are not synchronised. Because the module compares the refunded amount at Nets with the order before every online refund, a later online refund of that order is refused with Nets totals differ from native history. Reconcile them before refunding. Record such refunds with Refund Offline.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Nets Nexi Gateway is the first row of the VibeFox Nets Nexi 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-nets-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, Nets 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 Nets Easy is temporarily unavailable. Please try again. 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 refunds work.

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

Nets Easy does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the selected mode has a secret key: Test Secret Key in test mode, Live Secret Key in live mode. Payment setup shows a warning when the key is missing. 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: the webhook did not reach your store. Check that the storefront uses a public HTTPS address of at most 256 characters without "&" (see Webhooks) and that the secret key of the payment's environment is set. The order is also confirmed when the customer returns to the store after paying, or with Nets: check payment status and capture on the order page.

Webhook answers Unauthorized: the webhook did not carry the secret of that payment. Webhooks are only accepted with the secret registered with the payment.

Webhook answers Payment is busy, Payment lookup failed or Payment not reserved: another request was confirming the same cart, the Nets API could not be reached, or the reservation was not visible yet. Nets retries the webhook automatically.

Webhook answers Order update failed or Capture requires verification: the order could not be updated, or the charge could not be read back after the capture. Nets retries the webhook. Look at the log in Debug log to see the reason.

Webhook answers Unknown payment: the payment was not created by this store, for example a webhook of another shop on the same Nets account.

The webhook URL shows POST required in the browser: this is normal. The address accepts only requests from Nets.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Nets retries the webhook later, and the order is also confirmed when the customer returns.

The customer is back in the cart with Nets Easy is temporarily unavailable: set Debug log to Yes and look at the log at the bottom of the group. A wrong or missing secret key or a currency that Nets rejects is reported there. The order of that attempt is cancelled.

Order is On Hold after payment: read the order notes. If the capture was declined, retry with Nets: check payment status and capture or charge it in the Nets portal. If the amount or currency differs, check the payment in the Nets portal. If the capture result is uncertain, verify in the Nets portal whether it was charged.

Refund fails: refunds are only possible after the payment has been charged, from the invoice of the order. A refund uses the secret key of the environment in which the order was paid, so that key must be set. A previous refund requires reconciliation in Nets portal. or The previous refund response is uncertain. Verify it in Nets portal. means that an earlier refund had no clear answer from Nets: check it in the Nets portal first.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold) cannot be refunded online.

For developers: the Magento events nng_create_payment_payload and nng_currency_decimals let you change the Nets payment request and the number of decimals of a currency.

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_NetsNexiPayment. It removes the data and the code.

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

The license key and license status are always removed. If Delete settings on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Nets payment attempts, refunds and events are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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