VibeFox Netopia 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 with the OpenSSL, DOM and SimpleXML extensions.

Currency: the customer must check out in RON, EUR, USD or GBP. EUR, USD and GBP must be enabled on your Netopia account. For other currencies the payment method is hidden at checkout. The order is charged in its own currency.

Netopia account: you need a Netopia Payments seller account with a point of sale. From its technical settings you need the account signature and, for each environment you use (sandbox and live), the public certificate (.cer) and the private key (.key). Nothing has to be set up on the Netopia side: the IPN address is sent with every payment request.

Public store: the IPN (confirm) URL must be reachable from the internet, not behind a login, basic authentication or a firewall. Orders get their status only from the Netopia IPN.

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_netopia_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_netopia_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_netopia_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 Netopia 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. In the Netopia admin open your point of sale, copy the account signature and download the certificate and private key of the sandbox and of the live environment. Paste the signature and the full file contents into the settings (see Configuration).

5. Turn on Enable/Disable and click Save. Test a payment in sandbox mode, then turn off Test mode to take real payments.

OpenCart 4

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

4. Enter the license key, the account signature, the certificates and the private keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the IPN URL is different (see Configuration).

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 Netopia 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 account signature, certificate or private key of the active environment is missing (the payment method is then hidden at checkout), and shows Test mode is on: payments go to the Netopia sandbox 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 may have up to 128 characters, Sort order must be a whole number (negative numbers are allowed), Minimum total a number of 0 or more, and the geo zone and order statuses must exist; if any of these is wrong, nothing is saved. An invalid certificate or private key is rejected with an error in red and the previous value is kept, while the other fields are saved (Settings saved, except the values shown in red.). If the payment method is enabled but the active environment is incomplete, the save shows a warning.

IPN (confirm) URL

The first section shows the IPN (confirm) URL read-only. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_netopia_gateway/notify, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_netopia_gateway/payment/wcp_netopia_gateway.notify. It is built from the storefront address of your OpenCart installation. It is sent with every payment request as the confirm URL, so you do not need to enter it in the Netopia admin. Netopia sends the IPN to this URL. The extension decrypts it with the private key of the environment the payment was started in and checks your account signature and the payment request. Netopia reports these actions:

confirmed: the payment was made and captured. The order gets the paid status, or an awaiting order is marked paid.

paid: the payment is authorized (pre-authorization). The order waits in the awaiting status until you capture it in the Netopia admin.

confirmed_pending, paid_pending: the payment is under review at Netopia. The order waits in the awaiting status.

canceled: the payment was cancelled. An awaiting order is cancelled; an order without a status stays without one and the customer can pay again.

credit: a refund was made in the Netopia admin. It is recorded on the order.

A notification with a Netopia error code (for example a declined card) sets an awaiting order to the payment error status; an order without a status stays without one and the customer can pay again. Notifications that cannot be decrypted, carry another account signature or do not answer a payment request of that order in that environment are rejected and change nothing. Notifications of payments already started are accepted even if you turn the payment method off.

Checkout

Enable/Disable: Enable Netopia Payments turns the payment method on or off. Default: off.

Title: the payment method title shown at checkout. It is also the payment method name stored in the order. Up to 128 characters; leave it empty to use the default. Default: Card Payment (Netopia).

Description: the text shown to the customer at the Confirm Order step. Default: Pay securely with your credit or debit card via Netopia.

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

Geo zone: offer Netopia only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Minimum total: the order total, in the default currency of the store, that an order must reach before Netopia is offered. Leave it empty for no minimum.

Netopia account

In the Netopia admin go to Seller accounts > your point of sale > Technical settings: copy the account signature and download the public certificate (.cer) and the private key (.key) of each environment. Open the files in a text editor and paste their full content, including the BEGIN/END lines. The section links to the Netopia v1 documentation.

Account signature: the seller account signature (format XXXX-XXXX-XXXX-XXXX-XXXX), the same for sandbox and live.

Test mode: uses the Netopia sandbox (sandboxsecure.mobilpay.ro) and the sandbox keys. Default: on. Turn it off to take real payments with the live keys (secure.mobilpay.ro). While it is on, customers see Test mode (Netopia sandbox): no real money is charged. at the Confirm Order step.

Sandbox public certificate (.cer): the content of the sandbox public certificate file. It is used to encrypt the payment request.

Sandbox private key (.key): the content of the sandbox private key file. It is used to decrypt the IPN.

Live public certificate (.cer): the content of the live public certificate file.

Live private key (.key): the content of the live private key file.

Saved private keys are never shown again. The field stays empty, and its help text starts with A private key is saved. Leave it empty to keep the saved key, or paste a new key to replace it. To remove a saved key, tick Clear the saved private key on save under the field and click Save. An empty certificate field removes the certificate.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only when Netopia reports the payment. OpenCart has no Netopia order statuses of its own, so each field below lists your OpenCart order statuses. Notes on the order explain each change.

Order status after payment: the status of a paid order.

Processing: the Processing status below (default).

Completed: the Completed status below.

Processing status: default Processing.

Completed status: default Complete.

Awaiting Netopia payment: a pre-authorization waiting for capture in the Netopia admin, or a payment under review at Netopia. Default: Pending.

Netopia payment on hold: the payment needs your review (see Order statuses). Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here. The extension keeps the awaiting and on-hold cases apart even when both use the same status.

Canceled status: Netopia cancelled the payment of an awaiting order. Default: Canceled.

Payment error status: Netopia reported an error, for example a declined card, for an awaiting order. Default: Failed.

Refunded status: nothing is left to refund after the refunds made in the Netopia admin. Default: Refunded.

Advanced

Debug log: writes requests and IPN processing to netopia_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to netopia_p_debug.old.log.php. Card data, keys and customer details are not logged. Errors, for example rejected IPNs, 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 extension removes the gateway settings and the log. Orders and the Netopia payment records are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file, with the certificates. Private keys are not exported.

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

Checkout

At the Payment Method step the customer chooses the payment method (by default Card Payment (Netopia)). At the Confirm Order step the customer sees your description and the note You will be redirected to the Netopia secure page to pay with your card. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension builds the payment request, encrypts it with the Netopia certificate of the active environment and sends the customer straight to the Netopia payment page. The request contains the order total in the order currency, Order # with the order number, and the billing and shipping contact details with the order telephone. In sandbox mode it goes to the Netopia sandbox. 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 customer pays by card on the Netopia page and returns to your store. The return itself never pays an order. The order is marked paid only after Netopia confirms it by the IPN. 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. For an awaiting order the page shows Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. For an order on hold it shows Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. When an awaiting order or an order on hold later gets its final status (paid, payment error or cancelled), the customer is notified by e-mail with the new status. For a cancelled order it shows The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. For an order with a payment error it shows The payment was declined by Netopia.

If the IPN has not arrived yet when the customer comes back, a Payment confirmation page shows the same "not confirmed yet" text with the buttons Check again and Back to checkout. The order gets its status as soon as the IPN arrives.

If Netopia reported a cancellation or a decline for an order without a status, the customer is back at checkout with The payment was cancelled at Netopia. You can try again or choose another payment method. or The payment was declined by Netopia. You can try again or choose another payment method. On OpenCart 4 these messages are shown above the checkout page. The cart is kept. Each new attempt is a new payment request; earlier requests stay valid, so a late IPN of an earlier attempt is still recorded. 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 payment request. When another order of the same cart has already been paid or is awaiting or on hold, the customer goes to the success page and no new payment is started.

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 its pre-authorization was cancelled, it was declined after awaiting, or you cancelled or refunded it), the customer is sent back to the checkout with Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order., 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 the payment cannot be started, the customer stays at the Confirm Order step with a message above the button: Netopia gateway is not configured properly. Please contact the store administrator., Netopia cannot process payments in plus the currency, This order has nothing to pay. or Payment encryption failed. Please try again or contact support. The technical reason is written to the log.

The IPN 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 Netopia.

The extension takes card payments through the Netopia v1 card protocol only. It has no refunds or capture from OpenCart, no saved cards or one-click payments, no subscriptions, installments or other payment methods, and no Netopia API v2.

Orders and refunds

Order statuses

No status (missing order): the customer was sent to Netopia and has not paid, Netopia has not sent the IPN yet, or the payment was cancelled or declined before any result. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Processing or Completed status: Netopia confirmed the payment. The status follows Order status after payment. A note shows the amount, the masked card number and the Netopia transaction; sandbox payments are marked [sandbox].

Awaiting Netopia payment: the payment is a pre-authorization waiting for capture in the Netopia admin, or it is under review at Netopia. The order moves to the paid status when Netopia confirms it.

Netopia payment on hold: the invoice amount or currency differs from the order, only part of the payment was captured, Netopia confirmed the payment of a cancelled order or of an order placed with another payment method, or a sandbox (test) payment was confirmed while the store is in live mode (no real money was received). The order is not marked paid; the note explains it. Check the transaction in the Netopia admin, then process the order or refund the payment there.

Payment error status: Netopia reported an error, for example a declined card, for an awaiting order.

Canceled status: Netopia cancelled the payment of an awaiting order.

Refunded status: the payment was fully refunded in the Netopia admin.

Late notifications never downgrade a paid or closed order. If Netopia confirms another payment for an order that is already paid, a note asks you to refund the duplicate in the Netopia admin. If the customer pays a second order of the same cart, that order stays without a status and the payment request is marked as a duplicate payment of the cart.

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

VibeFox Netopia Gateway tab

In Sales > Orders open an order paid with Netopia. At the bottom of the order page, next to History and Additional, the VibeFox Netopia Gateway tab shows the Netopia Payments block: the Netopia transaction, the environment (sandbox or live), the payment request, the request status, the last IPN action, the masked card, the paid, refunded and remaining amounts, the refund history and the Netopia notes of the order. The tab is read-only and is shown to users who have access to the extension.

Refunds

Refunds and captures are not made from OpenCart: the Netopia v1 card protocol has no refund call. Refund the transaction in the Netopia admin. Netopia then sends a credit IPN, and the extension records the refund on the order automatically with the note Netopia refund processed: and the amount. A partial refund keeps the order status; when nothing is left to refund, the order is set to Refunded status. For EUR, USD and GBP orders the refunded amount, which Netopia reports in RON, is converted back to the order currency. A refund is never recorded twice and never for more than the remaining amount. If Netopia reports an error for the refund, only a note is added.

Product returns in Sales > Returns do not send money back through Netopia.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Netopia Gateway is the first block on Extensions > Extensions > Payments > VibeFox Netopia 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-netopia 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, Netopia 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 made in the Netopia admin are still recorded.

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

Netopia does not appear at checkout: check that the license is active, Enable/Disable is on, the active environment is complete (Account signature plus the certificate and private key of the sandbox in test mode, or of live in live mode) and the customer checks out in RON, EUR, USD or GBP. The settings page shows a warning when something is missing. Also check that the payment address is in the selected Geo zone and that the order reaches the Minimum total.

The payment went through, but the order stays without a status: the IPN did not reach your store or was rejected. Check that the IPN (confirm) URL from the settings is reachable from the internet (no basic authentication or firewall). Look at the Log field on the extension page: rejected IPNs are always logged. Turn on Debug log to see every IPN. The customer's return alone never pays an order.

Log shows failed decrypting data: the private key does not match the certificate Netopia used. The IPN is decrypted with the saved private key of each environment, so keep the key of the other environment saved while its payments are still open. Netopia retries the IPN.

Log shows signature mismatch: the Account signature differs from the point of sale that sent the IPN. Copy it again from the Netopia admin.

Log shows unknown payment request: the IPN does not answer a payment request your store made for that order in that environment (sandbox or live). Nothing is changed.

Log shows gateway not configured: no private key or no account signature is saved. Netopia retries the IPN, and the payment is recorded once the settings are complete.

Log shows busy, retry later or processing failed: the cart was being processed by another request at the same moment, or the order status could not be set. Netopia retries the IPN automatically.

Error on save about the certificate or private key: the pasted text is not a valid certificate or key. Paste the full file content including the BEGIN/END lines. The previous value was kept.

The customer sees This payment method is not available. Please reload the checkout page.: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

Order is in the on-hold status after payment: read the notes in the VibeFox Netopia Gateway tab (see Order statuses). The amount or currency differed, only part was captured, the order had been cancelled, or a sandbox payment was confirmed while the store is in live mode. Check the transaction in the Netopia admin.

A refund made in Netopia does not appear on the order: the credit IPN did not reach the store or was rejected. Check the log.

For developers: the list of accepted currencies can be changed with the OpenCart event netopia_p_supported_currencies.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Netopia 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, Minimum total and the OpenCart statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the IPN through in maintenance mode). If Delete data on uninstall is on, the other gateway settings (title, description, account signature, test mode, certificates, private keys, order status after payment, logging) and the log are removed. If it is off, they are kept for a later re-install. The Netopia payment records are always kept, so a late IPN of a payment started before a re-install still finds its order. 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 Netopia Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Netopia Payments and mobilPay are trademarks of their respective owners. This extension is not affiliated with or endorsed by Netopia Payments.