VibeFox ifthenpay for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: euro (EUR) only. The payment method is hidden when the store or order currency is not 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

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_ifthenpay_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate. The plugin generates its anti-phishing key.

3. Open the settings: WooCommerce > Settings > Payments > ifthenpay > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Choose the Payment Method and enter its ifthenpay key. Save, so that the Callback URL matches the chosen method.

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

7. Turn on Enable/Disable.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > ifthenpay. Without the key of the selected method the payment method is not shown at checkout, and the list of payment methods marks it as needing action. When you save an enabled gateway without that key, the page shows ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.

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

Title: the payment method title displayed at checkout. Default: ifthenpay.

Description: the payment method description displayed at checkout. 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.

ifthenpay keys

The keys (format ABC-123456) are shown in the ifthenpay backoffice 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.

Callback (payment notifications)

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 below. 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 plugin, 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. It starts like https://your-site/wc-api/ifthenpay_payment_callback/ and continues with the parameters of the method. Copy the whole URL exactly as the settings show it.

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 an order of this gateway: 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 its card request. Without a working callback, Multibanco and MB WAY orders are never confirmed, and card payments are confirmed only by the signed return.

Advanced

Test Mode: Enable test/sandbox 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. Checkout shows a TEST MODE badge. Default: off.

Order Status After Payment: the order status set after a confirmed payment, with one status change and one customer e-mail. Orders that contain only virtual downloadable products are always completed by WooCommerce.

Debug Log: Enable logging. API requests and callbacks are written to WooCommerce > Status > Logs, source wcp_ifthenpay_gateway. Errors are always logged. Keys, the anti-phishing key and phone numbers are never logged. Default: off.

Delete Data on Uninstall: Remove the plugin settings, the anti-phishing key and the logs when the plugin is deleted (orders are kept). Default: off.

Checkout

Multibanco. At checkout the customer sees You will receive a Multibanco reference to complete the payment. When the order is placed, the plugin creates a dynamic Multibanco reference for the order total. The order goes On hold, stock is reduced and the cart is emptied. The thank-you page and the order e-mails sent while the order is on hold show Multibanco Payment Details: entity, reference and amount, with Please use these details to pay at any Multibanco ATM or through your online banking. If the customer places the order again with the same amount, the same reference is reused. The order is confirmed 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 billing phone is filled in. The plugin sends a payment request to the phone, the order goes On hold, stock is reduced and the cart is emptied. The thank-you page says A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. All requests of the order are kept, so an earlier request approved in the app is still accepted. The order is confirmed by the callback.

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 Pending payment until it is paid, and stock is not reduced before. After a successful payment the customer returns to your store. The return is accepted only with a valid ifthenpay signature, the order key, a secret of that attempt and the card request of the order; then the order is marked paid. If the return cannot be verified, the order is not changed, and the thank-you page shows Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. A failed card payment marks the order Failed, and a cancelled one leaves it Pending payment. In both cases the customer goes to the Pay for order page 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.

The order is marked paid only after ifthenpay confirms the payment, and the amount is checked to the cent against the order total. If the payment cannot be started, the customer sees a short message, 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 payment method works on the classic checkout, on the Cart and Checkout blocks (with the MB WAY phone field) and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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

On hold (waiting for payment): a Multibanco reference was issued or an MB WAY request was sent. Unpaid references are not cancelled automatically; cancel such orders yourself if needed.

Pending payment: a card payment was started and is not confirmed yet, or was cancelled.

Processing or Completed: the payment was confirmed. The status follows Order Status After Payment. The order note shows the Multibanco entity and reference, the MB WAY transaction or the card request ID.

On hold after payment: the amount received was different from the order total, or the payment arrived after the order was cancelled. The order note explains it. Check the payment in the ifthenpay backoffice and complete or refund the order manually.

Failed: the customer returned from the card page with an error.

A second payment notification for an order that is already paid only adds a note to check for a duplicate payment in the ifthenpay backoffice. Refunded orders, and orders cancelled after payment, are never reopened.

Refunds

Refunds from WooCommerce are not supported. Refund the payment in the ifthenpay backoffice and record it in WooCommerce manually. A refunded (DEVOLVIDO) callback only adds an order note. Other statuses reported by ifthenpay also only add a note.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > ifthenpay. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 currency is EUR and the total is between 0.01 and 99,999.99 EUR. On the Pay for order page the order currency counts.

The customer paid, but the order stays On hold or Pending payment: 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 site must be reachable from the internet, not on localhost and not behind a login. Look for Callback rejected lines in WooCommerce > Status > Logs, source wcp_ifthenpay_gateway.

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 settings page once; ifthenpay retries the callback.

Callback answers Order not found: the reference or request does not belong to an order of this gateway, for example because the payment method was switched after the order was placed.

Why was a paid order put On hold? The amount received was different from the order total, or the payment arrived after the order was cancelled. Read the order note, 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the anti-phishing key and the logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Orders and their ifthenpay data (references, request IDs) are always kept. Existing orders keep their payment notes and transaction IDs.

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