VibeFox Montonio 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.

Currency: the checkout currency must be EUR or PLN. For any other currency the payment method is hidden at checkout.

Montonio account: you need the access key and the secret key of your store from the Montonio Partner System. Sandbox and live keys are different, so you need a pair for each environment you use. Nothing else has to be set up in Montonio: the notification address is sent with every payment.

Public site: your store must be reachable from the internet to receive Montonio notifications. Otherwise orders still get their status when the customer returns to the store.

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_montonio_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_montonio_payment.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_montonio_payment-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 Montonio Payment 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 Montonio Partner System open Stores > your store > API keys and copy the sandbox access key and secret key. Paste them into the settings and keep Sandbox mode on.

5. Turn on Enable/Disable, click Save and test a payment in the sandbox with an order in EUR. Then enter the live keys and turn off Sandbox mode.

OpenCart 4

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

4. Enter the license key and the Montonio keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Notification URL).

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Montonio Payment > 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 keys of the current environment are missing (the payment method is then hidden at checkout) and when the default currency of the store is not EUR or PLN, and shows Sandbox mode is on: payments are simulated and no real money is charged. while the sandbox is on. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must be 1 to 128 characters long, Sort Order must be a whole number (negative numbers are allowed), Total must be a number, 0 or greater, and the geo zone and order statuses must exist. If any value is wrong, nothing is saved and the page names the field.

Montonio

Enable/Disable: Enable Montonio bank payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order and the method name shown on the Montonio page. Default: Bank payment (Montonio). Required, up to 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay directly from your bank account. You will be redirected to Montonio to choose your bank.

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

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

API keys

Get the keys in the Montonio Partner System (the page links there) under Stores > your store > API keys. Sandbox and live keys are different. The sandbox uses only the sandbox keys, live mode only the live keys.

Sandbox mode: uses the Montonio sandbox (test payments, no real money). It switches both the Montonio API address and the key pair. Default: on. Turn it off only after entering the live keys. Payments made in the other environment keep using the keys of their own environment for confirmations and refunds. While it is on, customers see SANDBOX MODE — test payment, no real money is charged. at the Confirm Order step.

Sandbox access key: the access key (UUID) of your store in the Montonio sandbox.

Sandbox secret key: the secret key of your store in the Montonio sandbox.

Live access key: the access key (UUID) of your store in the live Montonio environment.

Live secret key: the secret key of your store in the live Montonio environment.

Saved secret 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 secret key, tick Clear the saved key on save under the field and click Save.

Notification URL: the address Montonio sends payment notifications to. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_montonio_payment/notification, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_montonio_payment/payment/wcp_montonio_payment.notification. It is built from the storefront address of your OpenCart installation. You do not need to enter it anywhere: the extension sends it to Montonio with every payment.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Montonio has confirmed the payment. Each field below lists your OpenCart order statuses.

Order Status After Payment: the status set after a verified Montonio payment. Default: Processing.

Payment On Hold Status: the payment needs attention (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.

Payment Failed Status: set when the bank rejects a payment that was on hold as authorized. Default: Failed.

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

Advanced

Debug log: writes payment events to wc_mnt_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 wc_mnt_debug.old.log.php. Errors and warnings are always logged, even when this option is off. Keys, tokens and customer data are never logged. Default: off.

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

Delete data: when on, uninstalling the extension removes the gateway settings and its log. Disabling the extension never deletes anything. Order data (Montonio UUIDs, notes) is always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Access keys and secret keys are not exported.

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

Payment notifications

Montonio tells your store about each payment with a signed token. The token arrives in two ways: by a server-to-server notification to the notification URL and with the customer when they return to the store. Both are checked: the signature with the secret key of the environment the payment was created in, the expiry time, your access key, and that the payment is one your store created for that order. A token signed with the key of the other environment is rejected. Each status is applied only once, so repeated notifications do not add notes, e-mails or stock changes. The notification URL 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 Montonio.

Checkout

At the Payment Method step the customer chooses the payment method (by default Bank payment (Montonio)). At the Confirm Order step the customer sees the Montonio icon and your description. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension creates a Montonio payment for the order total in the order currency and sends the customer to the Montonio payment page. There the customer picks a bank and pays. 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. Banks of the customer's billing country are shown first (Poland for PLN orders). The payment shows as Order and the order number. The Montonio page opens in the store language when it is German, English, Estonian, Finnish, Lithuanian, Latvian, Polish or Russian, otherwise in English.

The order is marked paid only after Montonio confirms it: by the notification or with the customer's return. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success page with Your Montonio bank payment has been received. If the bank has not confirmed the payment yet, or the order is on hold, the page shows We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. If the bank later rejects an authorized payment, the page shows Your Montonio payment was not completed. Please contact us about this order.

If Montonio reports the payment as still pending when the customer comes back, a Payment confirmation page shows the same text with a Check again button and a Back to checkout button. Check again asks Montonio for the current status of the payment. The notification sets the order status as soon as it arrives.

If the payment was cancelled or rejected, the customer is back at checkout with one of these messages: The payment was cancelled or rejected by the bank. You can try again or choose another payment method., The payment was not completed. You can try again or choose another payment method. or Montonio could not complete the payment. Please 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 Montonio payment. Before creating a new payment, the extension asks Montonio about the previous attempt of the same cart. If it is already paid, that payment is confirmed, the customer goes to the success page and no second payment is made.

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), 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 Montonio, and the next Confirm Order pays a new order. On OpenCart 3 the return of such an order shows the success page with the note that the payment was not completed. If the order of the checkout is already placed and the cart has changed since, the message is Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. A change of the cart, including a new quantity, counts as a new cart that needs its own payment. An order of the cart that was paid and then cancelled or refunded no longer holds the cart.

If Montonio cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, for example Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method. The technical reason is written to the log.

The extension takes bank payments (payment initiation) only. It has no card payments, BLIK, Apple Pay or Google Pay, Pay Later or financing, Montonio shipping, subscriptions, saved payment methods or bank selection on your own site.

Orders and refunds

Order statuses

No status (missing order): the customer was sent to Montonio and has not paid, Montonio reports the payment as pending, or the payment was cancelled or not completed. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): Montonio confirmed the payment (PAID) with the exact order amount and currency. A note shows the bank, the Montonio order UUID, the amount and the environment.

Payment On Hold Status (default Pending): the bank has not confirmed the payment yet (AUTHORIZED); the order moves to Order Status After Payment when Montonio reports PAID. An order is also put on hold when Montonio reported a different amount or currency than the order total, when a sandbox payment arrived while the store is in live mode (no real money was received), or when the payment arrived after the order had been given another status, for example cancelled. The note explains it. Check the payment in the Montonio Partner System and fulfil the order or refund the payment.

Payment Failed Status (default Failed): the bank rejected a payment that was on hold as authorized. Only the latest payment attempt of the order can change it.

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

Paid or refunded orders are never reopened by later notifications. If a second payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the second payment in the Montonio Partner System.

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

VibeFox Montonio Payment tab

In Sales > Orders open an order paid with Montonio. At the bottom of the order page, next to History and Additional, the VibeFox Montonio Payment tab lists the payment attempts of the order with the date, the Montonio order UUID (with a Sandbox label for test payments), the amount, the bank, the Montonio status and the result. Below are the amounts Paid / refunded, the refund form, the refund history and the Montonio notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Montonio Payment tab enter the amount (the amount not refunded yet is filled in), optionally a reason (it is kept in the order note only), and click Refund via Montonio. Confirm the question Refund this amount through Montonio? This cannot be undone. Full and partial refunds are supported. You need the right to modify the extension (set in System > Users > User Groups). Refunds are limited to the amount Montonio charged, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. The refund is sent to the environment the payment was made in (sandbox or live), so that environment's keys must be set. If Montonio does not accept the refund, the tab shows the error and no refund is recorded. A sent refund is added to the refund history and the notes with its status and the Montonio refund ID. A full refund sets the order to Refunded Status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status. Refunds are available once Montonio has reported the payment as paid.

Montonio confirms or rejects each refund later by a notification. A confirmation is added to the notes. If Montonio rejects the refund, the note says that the money was not returned to the customer; check it in the Montonio Partner System and correct the refund in OpenCart.

Product returns in Sales > Returns do not send money back through Montonio. Refunds made in the Montonio Partner System are added to the notes when Montonio reports them. The order status is not changed automatically. Update it manually if needed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Montonio Payment is the first block on Extensions > Extensions > Payments > VibeFox Montonio Payment > 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-montonio 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, Montonio 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

Montonio does not appear at checkout: check that the license is active, Enable/Disable is on and both keys of the current environment are set: Sandbox access key and Sandbox secret key in sandbox mode, Live access key and Live secret key in live mode. The settings page shows a warning when keys are missing. The customer must pay in EUR or PLN (the currency selected in the store). 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 notification did not reach your store. Check that the store is reachable from the internet and that the keys in the settings belong to the environment of the payment. The order also gets its status when the customer returns to the store after paying, when the customer clicks Check again, and when the customer tries to pay the same cart again.

Notification answers Invalid token: the token signature, expiry or access key did not match. Check that the access key and secret key are copied correctly and belong to the right environment, and that the server clock is correct. A token signed with the key of the other environment is also rejected.

Notification answers Payment does not belong to this order: the payment was not created by this store for this order. This happens when two stores use the same Montonio account and order numbers.

Notification answers Gateway not configured: no Montonio keys are set, or the keys of the payment's environment are missing. Enter the keys; Montonio retries the notification.

Notification answers Temporarily unavailable: the cart was being confirmed by another request at the same moment, or the order status could not be set. Montonio retries the notification. Look at the Log field for the reason.

The customer sees an error after Confirm Order: look at the Log field on the extension page. This payment method is not available. Please reload the checkout page. means the checkout session no longer matches the order, or the payment method was turned off meanwhile: the customer reloads the checkout. This payment method is temporarily unavailable. Please choose another payment method. usually means wrong or missing keys. Montonio could not start the payment. Please check your order details or choose another payment method. means Montonio refused the payment data; the log has the reason.

Order is in the on hold status after payment: read the notes in the VibeFox Montonio Payment tab (see Order statuses), then fulfil the order or refund the payment.

Sandbox payments do not confirm a live order: a sandbox payment never confirms an order while the store is in live mode; the order is put on hold instead. Switch Sandbox mode to the environment you want and use that environment's keys.

No refund form in the tab: the tab says why: the payment is not confirmed yet, it is fully refunded, or your user group has no right to modify the extension.

Refund fails with a message about the environment: the payment was made in the sandbox or live environment, and the keys of that environment are not set. Enter them and try again. The order is being updated by a payment notification, try again in a moment. means a notification is being processed for the same order.

For developers: the extension triggers the OpenCart events wc_mnt_supported_currencies, wc_mnt_order_data and wc_mnt_locale to change the supported currencies, the payment data and the Montonio page language.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Montonio Payment. 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 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 notifications through in maintenance mode). If Delete data is on, the other gateway settings (title, description, sandbox mode, keys, debug log) and the log are removed. If it is off, they are kept for a later re-install. The Montonio payment and refund records are 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 Montonio Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Montonio is a trademark of its respective owner. This extension is not affiliated with or endorsed by Montonio.