VibeFox Nets Nexi 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.

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.

Currencies and payment methods: the extension does not restrict currencies itself. Use the currencies enabled in your Nets account; an unsupported currency is reported by Nets when the payment is created. Which payment methods the customer sees 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 store needs HTTPS to receive webhooks. Without it 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 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_nets_nexi_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_nets_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_nets_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 Nets Nexi 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. Copy the test secret key from the Nets Easy test portal and paste it into Test Secret Key (see Configuration). Nothing has to be set up in the Nets portal.

5. Turn on Enable/Disable, keep Test Mode on, click Save and place a test order. Then enter the live secret key and turn off Test Mode.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_nets_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 Nets Nexi Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the secret keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the webhook address is different (see Webhooks).

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 Nets Nexi Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the secret key of the selected mode is missing, for example Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., and shows Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. while test mode is on. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty (up to 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 field is wrong, nothing is saved.

Nets Nexi (Nordics)

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

Title: the payment method title displayed to customers during checkout. It is also the payment method name stored in the order. Default: Nets Easy. Required.

Description: the text shown to the customer at the Confirm Order step. Default: Pay securely with Nets Easy.

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

Geo Zone: offer Nets 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 Nets is offered. Leave it empty to offer Nets for any total.

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 section links to both portals. The checkout keys are not needed.

Test Mode: test mode uses test.api.dibspayment.eu with the test secret key; live mode uses api.dibspayment.eu with the live secret key. Refunds and captures of an order always use the environment in which it was paid. Default: on. While it is on, customers see Test mode: no real money will be charged. at the Confirm Order step.

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

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

Saved 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 key on save under the field and click Save.

Payment

Webhooks: Nets notifications (webhooks) are registered automatically with every payment. There is nothing to configure in the Nets portal. The field shows the address they are sent to. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_nets_nexi_gateway/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_nets_nexi_gateway/payment/wcp_nets_nexi_gateway.webhook. It is built from the storefront address of your OpenCart installation. If it is not a public HTTPS address, the field warns you that the store does not receive webhooks; payments are then 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 extension created for that payment. Webhooks without the correct secret are rejected. The webhook only tells the extension which payment changed: the payment itself is always read from the Nets API with the secret key of the environment it was made in.

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after the payment was read back from the Nets API (webhook, the customer's return or Nets: check payment status and capture on the order page) and a matching reservation was charged. Each status field below lists your OpenCart order statuses.

Order Status After Payment: the status of the order once Nets has confirmed and charged the payment. Default: Processing. Choose Complete to mark paid orders as completed.

Nets Payment On Hold Status: the amount or currency differs from the order, the capture failed, or the customer paid after the order was cancelled. Nothing is captured automatically, and a note explains why. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled Status: set when the reservation of the order is cancelled in the Nets portal. Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

Debug log: logs API calls and payment status changes to nng_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. Keys and customer data are not logged. Errors and warnings are always logged, also while it 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 Nets payment and refund records of orders are always kept. Default: off.

Import / Export

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

Import: paste previously exported JSON and click Import to restore the settings. Saved secret keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Nets Easy). At the Confirm Order step the customer sees your description and the note You will be redirected to the Nets payment page to pay securely. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension creates a Nets payment for the order total in the order currency, with the products, shipping and the other order totals (coupons, vouchers, fees) as order lines, and sends the customer to the Nets hosted payment page. On OpenCart 4 the customer picks the payment method 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. The payment reference at Nets is the OpenCart order number. The customer's e-mail, name, shipping address and phone number are passed to Nets when Nets accepts their format. The checkout terms page of your store is linked on the Nets page (the store home page if none is set).

After paying, the customer returns to your store. The order is marked paid only after Nets confirms it: the extension reads the payment from the Nets API, compares the reserved amount and currency with the order, charges the reservation and only then sets the order status. This happens on the webhook or when the customer comes back, whichever is 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. If the payment could not be confirmed yet (Nets could not be reached, or another request was confirming it at that moment), a Payment confirmation page shows Your Nets payment is being confirmed. Your order will be updated as soon as it is confirmed — please do not pay again. with the buttons Check again and Back to checkout.

If the customer cancels on the Nets page, they return to the checkout with The Nets payment was cancelled. You can try again or choose another payment method. If nothing was paid, the message is The payment was not completed. You can try again or choose another payment method. On OpenCart 4 these messages are shown above the checkout page. The cart is kept. 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 Nets payment. On a new attempt the extension first checks the previous payments of the cart; if one is already paid, that order is confirmed instead of a new payment. Otherwise the previous Nets sessions are closed before a new one starts. When another order of the same cart is already paid or on hold, the customer goes to the success page.

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 you cancelled it, also after cancelling the reservation in the Nets portal), 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 Nets, and the next Confirm Order pays a new order. An order of the cart that was paid and then cancelled or refunded no longer holds the cart.

If Nets cannot start the payment, the customer stays at the Confirm Order step with a short message, for example Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. or The payment service could not be reached. Please try again in a moment. An order total of zero gives The order total must be greater than zero to pay with Nets. The details are written to the log.

The webhook 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 Nets.

The extension uses the 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.

Orders and refunds

Order statuses

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

Order Status After Payment (default Processing): Nets confirmed and charged the payment. A note shows the payment ID, the charge ID and the payment method.

Nets Payment On Hold Status (default Pending): the amount or currency at Nets differs from the order (not captured), the capture was declined, or the customer paid after the order had been cancelled (reserved, not captured). The note explains it. Nothing is captured automatically. After reviewing the order, capture with Nets: check payment status and capture, or cancel the reservation in the Nets portal.

Cancelled Status (default Canceled): the reservation of the order was cancelled, for example in the Nets portal.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

When a webhook or the customer's return moves an order from the on-hold status to the paid status or cancels it, OpenCart notifies the customer. Repeated webhooks and reloads never charge twice or add duplicate notes, and a paid order is never changed again by Nets events. If an old payment link is completed for an order that is already paid, or for another order of the same cart, the second reservation is released automatically; if it was already charged, a note asks you to refund it in the Nets portal. If the order was marked paid in another way, a reserved Nets payment is not captured and a note says so.

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

VibeFox Nets Nexi Gateway tab

In Sales > Orders open an order paid with Nets. At the bottom of the order page, next to History and Additional, the VibeFox Nets Nexi Gateway tab shows the Nets Easy payment block: the payment ID, the charge ID, the environment (with a Test environment label for test payments), the status and payment method, the amounts reserved and charged at Nets, the order total and the amount refunded, the refund form, the refund history and the Nets notes of the order. The tab is shown to users who have access to the extension; its buttons need the right to modify the extension (set in System > Users > User Groups).

Nets: check payment status and capture: shown for orders that are not paid yet. 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. If nothing changes, a note explains why, for example that the customer has not completed the payment yet. A status set by this button, like a status set by a refund, is changed directly, as a manual status change, without e-mails and stock movements.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via Nets. Confirm the question Refund this amount through Nets? This cannot be undone. Full and partial refunds are supported once the payment is charged, up to the order total; a payment that is only reserved can be cancelled in the Nets portal. The refund goes to the charge of the order in the environment in which it was paid, so that environment's secret key must be set. If Nets does not accept the refund, the tab shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the Nets refund ID. A full refund sets the order to Refunded Status; a partial refund does not change the status.

Product returns in Sales > Returns do not send money back through Nets. Refunds made in the Nets portal are not synchronised; update the order manually if needed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Nets Nexi Gateway is the first block on Extensions > Extensions > Payments > VibeFox Nets Nexi 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-nets-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, Nets 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 refunds work.

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

Nets Nexi does not appear at checkout: check that the license is active, Enable/Disable is on and the selected mode has a secret key: Test Secret Key in test mode, Live Secret Key in live mode. The settings page shows a warning when the key is missing. 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: the webhook did not reach your store. Check that the store uses HTTPS, so that the address in Webhooks is a public HTTPS address, and that the secret key of the payment's environment is set. The order also gets its status when the customer returns to the store after paying, or with Nets: check payment status and capture in the order tab.

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 Unknown payment: the payment was not created by this store.

Webhook answers Busy, retry later, Payment lookup failed or Payment not reserved yet: 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 could not be updated, retry later: the order status could not be set. Nets retries the webhook. Turn on Debug log to see the reason.

The webhook URL shows Method not allowed in the browser: this is normal. The address accepts only requests from Nets.

The customer sees an error after Confirm Order: turn on Debug log and look at the Log field on the extension page. This payment method is temporarily unavailable. Please choose another payment method. usually means a wrong or missing secret key. A rejected currency is reported by Nets in the log. This payment method is not available. means the checkout session no longer matches the order, or the payment method was turned off meanwhile: the customer reloads the checkout.

The customer sees We could not match this payment to an order: the return link is incomplete or belongs to another order. If the customer was charged, find the payment in the Nets portal and check the order.

Order is in the on-hold status after payment: read the Nets notes in the tab. 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 customer paid after cancellation, review the order and capture or cancel the reservation.

Refund via Nets is missing or fails: refunds are only possible after the payment has been charged; the tab then shows a charge ID. A refund uses the secret key of the environment in which the order was paid, so that key must be set; otherwise the tab says which environment's key is missing.

For developers: before the payment is created, the extension triggers the OpenCart event nng_create_payment_payload with the request body and the order; nng_currency_decimals changes the decimals of a currency.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Nets Nexi 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 order statuses of the Payment section, which return to their defaults on a re-install. On OpenCart 4 the events of the extension and its startup action, which lets the webhook through in maintenance mode, are removed too. If Delete Data on Uninstall is on, the other gateway settings (title, description, test mode, secret keys, logging) and the log are removed. If it is off, they are kept for a later re-install. The Nets payment data of orders (payments, charges and refunds) is always kept, so orders paid before can still be refunded 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 Nets Nexi Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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