VibeFox ifthenpay 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: euro (EUR) only. The EUR currency must be enabled in your store, and the payment method is shown only when the customer pays in EUR. ifthenpay accepts totals from 0.01 to 99,999.99 EUR.

ifthenpay account: sign up at ifthenpay.com. You need the key of the method you offer: Multibanco, MB WAY or Credit Card (format ABC-123456). The keys are shown in the ifthenpay backoffice (backoffice.ifthenpay.com) or sent by ifthenpay when the method is activated for your account. ifthenpay must also activate the callback for your key (see Configuration), and your store must be reachable from the internet.

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_ifthenpay_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_ifthenpay_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_ifthenpay_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 ifthenpay Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list. The extension generates its anti-phishing key on install.

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. Choose the Payment Method, enter its ifthenpay key and click Save, so that the Callback URL matches the chosen method.

5. Copy the Anti-phishing Key and the Callback URL from the Callback section and ask ifthenpay to activate the callback for your key with them (in the backoffice or through ifthenpay support).

6. Turn on Enable/Disable and click Save.

OpenCart 4

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

4. Enter the license key, the method and its key, and activate the callback as in steps 3 to 6 for OpenCart 3. The settings page and its fields are the same in both versions. Only the callback URL is different (see Callback).

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Without the key of the selected method the payment method is not shown at checkout. While the gateway is enabled without that key, the page shows ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, the payment method must be valid, the title may have at most 128 characters, Sort Order must be a whole number, Total a number, 0 or greater, and the geo zone and order statuses must exist; otherwise nothing is saved.

ifthenpay

Enable/Disable: Enable ifthenpay Payment turns the payment method on or off. Default: off.

Title: the payment method title displayed at checkout. It is also the payment method name stored in the order. Default: ifthenpay. If you leave it empty, checkout shows ifthenpay.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay via Multibanco, MB WAY or Credit Card. Change it to match the method you offer.

Payment Method: the method offered at checkout. Only the key of this method is required.

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

Geo Zone: offer ifthenpay 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 ifthenpay is offered. Leave it empty to offer ifthenpay for any total. ifthenpay itself is offered only when the customer pays in EUR, for 0.01 to 99,999.99 EUR.

ifthenpay keys

The keys (format ABC-123456) are shown in the ifthenpay backoffice (the section links there) or sent by ifthenpay when the payment method is activated for your account.

Multibanco Key: your ifthenpay Multibanco (MB) key for dynamic references.

MB WAY Key: your ifthenpay MB WAY key.

Credit Card Key: your ifthenpay Credit Card key. It also verifies the signature of the customer's return from the card page.

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.

Callback

The callback tells your store that a payment has been made. Ask ifthenpay to activate the callback for each key you use, with the anti-phishing key and the callback URL of this section. Multibanco and MB WAY orders are confirmed only by the callback; card payments are also confirmed by the signed return from the card page.

Anti-phishing Key: generated by the extension, shown for copying. ifthenpay sends it back in every callback; callbacks without it are rejected.

Callback URL: the callback URL for the selected payment method, with the ifthenpay placeholders, shown for copying. On OpenCart 3 it starts like https://your-store/index.php?route=extension/payment/wcp_ifthenpay_gateway/callback, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_ifthenpay_gateway/payment/wcp_ifthenpay_gateway.callback. It is built from the storefront address of your OpenCart installation, and continues with the parameters of the method. Copy the whole URL exactly as the settings show it. If you change the Payment Method, save and copy the new URL.

The anti-phishing key in each callback is compared with yours. A missing or wrong key is answered with 403, and the order is not changed. The callback must also match a payment of this extension: for Multibanco by entity and reference, for MB WAY by the order and one of its MB WAY requests, for Credit Card by the order and one of its card requests. Without a working callback, Multibanco and MB WAY orders are never confirmed, and card payments are confirmed only by the signed return. The callback also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the callback and the customer's return from the card page through.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). With Multibanco and MB WAY the order gets the awaiting status as soon as ifthenpay has issued the reference or the MB WAY request; with Credit Card the order gets a status only from the callback or the signed return. An order is marked paid only when the amount matches the order total to the cent. Each field below lists your OpenCart order statuses.

Order Status After Payment: the status set when the payment is confirmed. Default: Processing.

Awaiting payment status: a Multibanco reference or MB WAY request was issued, and the customer still has to pay. The Multibanco details are sent with this status, in the order e-mail and in the customer's order history. Default: Pending.

Payment on hold status: ifthenpay reported a payment that does not match the order (amount, currency), a payment after the order was cancelled, or a payment of an order whose cart was already paid. 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.

Advanced

Test Mode: Credit Card and Multibanco use the ifthenpay sandbox endpoints; no real money is taken, and you use the test keys provided by ifthenpay. MB WAY has no sandbox: test it with a test key from ifthenpay. The Confirm Order step shows a TEST MODE badge. Default: off.

Debug Log: API requests and callbacks are written to ifthenpay_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web and is rotated at 5 MB. Errors are always logged. Keys, the anti-phishing key and full phone numbers are never logged. 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, the anti-phishing key and the log. Orders and the ifthenpay payment records always stay. Default: off.

Import / Export

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

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

Checkout

At the Payment Method step the customer chooses the payment method (by default ifthenpay). At the Confirm Order step the customer sees your description and the hint of the method. OpenCart creates the order at this step, still without a status.

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.

Multibanco. The customer sees You will receive a Multibanco reference to complete the payment. When the customer clicks Confirm Order, the extension creates a dynamic Multibanco reference for the order total, and the order gets the Awaiting payment status. The order success page shows Multibanco Payment Details: entity, reference and amount, with Please use these details to pay at any Multibanco ATM or through your online banking. The same details are sent in the order e-mail and appear in the customer's order history. A reference already issued for the order with the same amount is reused. The order is paid when ifthenpay sends the payment callback.

MB WAY. The customer enters the MB WAY phone number (912 345 678, +351 912 345 678, or 351#912345678 for other countries); the phone of the order is filled in. The extension sends a payment request to the phone, and the order gets the Awaiting payment status. The order success page says A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. The order is paid when ifthenpay sends the callback. Only a masked phone number is stored. By default OpenCart 4 does not ask for a telephone at checkout; the field is then empty and the customer enters the number.

Credit Card. The customer sees You will be redirected to a secure page to enter your card details. and is sent to the ifthenpay card page. The order stays without a status, and the cart is kept. After a successful payment the customer returns to your store. The return is accepted only with a valid ifthenpay signature, a secret of that attempt and a card request of the order; then the order is marked paid and the customer sees the OpenCart order success page. If the return cannot be verified, nothing changes, and a Payment confirmation page shows Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. with the buttons Check again and Back to checkout; the callback confirms the payment as soon as it arrives. If the card payment fails or is cancelled, the customer is back at checkout with The card payment was not completed. You can try again or choose another payment method. or The card payment was cancelled. You can try again or choose another payment method. Every card attempt of the order is kept, so a payment made in an older tab is still accepted. On OpenCart 4 these messages are shown above the checkout page.

When the payment is confirmed, the order gets its status the standard OpenCart way, with the usual order e-mails. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 updates the order of the checkout, so after a cancelled or failed card payment, or a declined MB WAY request, the customer pays the same order with a new attempt. If the same cart already has a paid order or an order awaiting a Multibanco or MB WAY payment, the customer goes to the success page of that order instead of starting a new payment. The Multibanco details and the MB WAY hint are shown on the success page only while the order is awaiting payment. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

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 an order awaiting a Multibanco payment), 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. If the order 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. In both cases the next Confirm Order pays a new order of the cart.

If the payment cannot be started, the customer stays at the Confirm Order step with a short message above the button, for example The Multibanco reference could not be created. Please try again or choose another payment method., The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. or The payment service is temporarily unavailable. Please try again in a few minutes. The technical reason is written to the log.

The extension offers one ifthenpay method at a time. It has no Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX or Pay-by-Link, no subscriptions or saved cards, no automatic expiry or cancellation of unpaid Multibanco references and no payment status polling.

Orders

Order statuses

No status (missing order): a card payment was started and is not confirmed yet, or it failed or was cancelled. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Awaiting payment status (default Pending): a Multibanco reference was issued or an MB WAY request was sent. Unpaid references and declined MB WAY requests do not cancel the order automatically; cancel such orders yourself if needed.

Order Status After Payment (default Processing): the payment was confirmed. A note shows the Multibanco reference, the MB WAY transaction or the card request ID, and how it was confirmed.

Payment on hold status (default Pending): the amount received was different from the order total (for example, the cart was changed after a card payment started), the payment arrived after the order was cancelled, or another order of the same cart was already paid. The note explains it, and the customer is not asked to pay again. Check the payment in the ifthenpay backoffice and complete or refund the order manually. A later correct payment for such an order does not change it.

A second payment for an order that is already paid only adds a note to check for a duplicate payment in the ifthenpay backoffice. An order you have moved to another status (for example refunded) is never reopened; a note is added.

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

VibeFox ifthenpay Gateway tab

In Sales > Orders open an order paid with ifthenpay. At the bottom of the order page, next to History and Additional, the VibeFox ifthenpay Gateway tab lists the payment attempts of the order (date, method, a Sandbox label for test payments, amount, Multibanco entity and reference or the masked MB WAY phone, ifthenpay request ID and status), a Payment on hold warning while the order is on hold, and the ifthenpay notes of the order. The tab is read only and is shown to users who have access to the extension.

Refunds

Refunds from OpenCart are not supported. Refund the payment in the ifthenpay backoffice and record it in OpenCart manually. Product returns in Sales > Returns do not send money back through ifthenpay. A refunded (DEVOLVIDO) callback only adds a note. Other statuses reported by ifthenpay also only add a note.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox ifthenpay Gateway is the first block on Extensions > Extensions > Payments > VibeFox ifthenpay 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-ifthenpay 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: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, ifthenpay 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.

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

ifthenpay does not appear at checkout: check that the license is active, Enable/Disable is on, the key of the selected Payment Method is filled in, the customer pays in EUR and the total is between 0.01 and 99,999.99 EUR. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The customer paid, but the order stays in the awaiting status or without a status: the callback is not reaching your store. Check that ifthenpay activated the callback URL and the anti-phishing key for the key you use, and that the URL is the one for the selected method. The store must be reachable from the internet, not on localhost and not behind a login. Turn on Debug Log and look at the Log field on the extension page.

Callback answers 403 Forbidden: the anti-phishing key in the callback is missing or differs from the one in the settings. Send the key shown in the settings to ifthenpay again.

Callback answers 503 Not configured: the anti-phishing key has not been generated yet. Open the extension settings once; ifthenpay retries the callback.

Callback answers 503 Busy: the same order was being processed by another request at that moment. ifthenpay retries the callback.

Callback answers Order not found: the reference or request does not belong to a payment of this extension, or the order was placed with another payment method.

Why was a paid order put on hold? The amount received was different from the order total, the payment arrived after the order was cancelled, or another order of the same cart was already paid. Read the notes in the VibeFox ifthenpay Gateway tab, check the payment in the ifthenpay backoffice and complete or refund the order manually.

MB WAY request could not be sent: the phone number is not linked to MB WAY or is in the wrong format. Use 912 345 678, or 351#912345678 for numbers of other countries.

Test mode and MB WAY: ifthenpay has no MB WAY sandbox; use a test key provided by ifthenpay.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox ifthenpay 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 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 callback and the customer's return through in maintenance mode). If Delete Data on Uninstall is on, the other gateway settings, the anti-phishing key and the log are removed; after a re-install a new anti-phishing key is generated and must be sent to ifthenpay again. If it is off, they are kept for a later re-install. The ifthenpay payment records (references and request IDs) are always kept, so callbacks for references issued before still find their orders 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 ifthenpay Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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