VibeFox ifthenpay for Adobe Commerce — Yardım

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

Currency: euro (EUR). ifthenpay charges euros only, so the payment method is shown only when the customer's cart is in euros. The base currency of your store may be another one, but the customer must pay in euros. 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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-ifthenpay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/IfthenpayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_IfthenpayPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush. The module generates its anti-phishing key on install.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox ifthenpay Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Choose the Payment Method, enter its ifthenpay key and click Save Config, so that the Callback URL matches the chosen method. Copy the Anti-phishing Key and the Callback URL shown in the Callback row and ask ifthenpay to activate the callback for your key with them (in the backoffice or through ifthenpay support). Then set Enable to Yes and click Save Config.

The module adds the ifthenpay payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the ifthenpay payment attempts and callbacks.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox ifthenpay Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Without the key of the selected method the payment method is not shown at checkout.

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a title for the payment method (1 to 128 characters). for an empty or too long Title; "Sort order" must be a whole number.; Order total must be a number, 0 or greater. for Minimum Order Total or Maximum Order Total (amounts accept "9.99" and "9,99").

While the payment method is enabled in the Default Config, the Callback row shows these warnings when they apply: ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. and ifthenpay test mode is on. MB WAY has no sandbox.

General

Enable: shows or hides ifthenpay at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: ifthenpay. Required, at most 128 characters.

Description: shown at checkout when the customer selects ifthenpay. 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 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.

Magento stores the keys encrypted and shows only a mask (******) after saving. Leave the mask, or an empty field, to keep the saved key; type a new value to change it. Spaces at the start and end are removed. To delete a saved key, set Clear saved Multibanco Key, Clear saved MB WAY Key or Clear saved Credit Card Key (at the end of the group) to Yes and click Save Config; these fields go back to No after saving.

Callback

The callback tells your store that a payment has been made. The Callback row shows, for copying:

Anti-phishing Key: generated by the module on install (or on the next Save Config, if it is missing) and stored encrypted. ifthenpay sends it back in every callback; callbacks without it are rejected. Saving the settings never changes an existing key.

Callback URL: the callback URL for the selected payment method, with the ifthenpay placeholders. It is the storefront address of the default store view and starts like https://your-store/wcpifthenpaygateway/callback/index/, followed by the parameters of the method, for example ?chave=[CHAVE_ANTI_PHISHING]&entidade=[ENTIDADE]… for Multibanco. Copy the whole URL exactly as the settings show it, and save the settings after changing Payment Method, so the row shows the URL of the new method.

Ask ifthenpay to activate the callback for each key you use, with these two values. Multibanco and MB WAY orders are confirmed only by the callback; card payments are also confirmed by the signed return from the card page. The callback is a GET request. 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 module: for Multibanco by entity and reference, for MB WAY by one of the cart's MB WAY requests, for Credit Card by the cart 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 module does not poll ifthenpay.

Test mode and order status

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. Checkout shows a TEST MODE note under the payment method. Default: No.

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

Conditions

Payment from Applicable Countries: All Allowed Countries offers ifthenpay for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer ifthenpay only for billing addresses in these countries.

Minimum Order Total: offer ifthenpay only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer ifthenpay only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

These conditions come on top of the euro currency and the ifthenpay amount range of 0.01 to 99,999.99 EUR.

Advanced

Debug log: writes the ifthenpay API requests and answers to var/log/ifthenpay_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged. Keys, the anti-phishing key, return secrets, e-mails and phone numbers are redacted. At 5 MB the log starts again and the previous one is kept as ifthenpay_p_debug.old.log.php. Default: No.

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

Remove data on uninstall: when Yes, uninstalling the module with its data removes the settings, the anti-phishing key and the log (see Uninstall). Orders and the ifthenpay payment records always stay. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default ifthenpay) and sees the ifthenpay logo, the description and a note for the selected method: After placing the order, you will receive Multibanco payment details., Confirm the payment request in your MB WAY app. or You will be redirected to ifthenpay to complete your card payment. After Place Order, Magento places the order in Pending Payment. No invoice is created. The module then creates the ifthenpay payment for the order total in euros. What happens next depends on Payment Method.

Multibanco: the module creates a dynamic Multibanco reference and sends the order e-mail. The order success page shows ifthenpay payment instructions with the Multibanco Entity, the Reference (in groups of three digits), the Amount and Pay using the entity and reference above at an ATM or in your online banking. Payment is confirmed after the ifthenpay callback. The same details are in the payment information of the order e-mail and of the order in the customer account while the order waits for payment.

MB WAY: at checkout the customer enters MB WAY phone number, filled in with the phone of the billing address: 912 345 678, +351 912 345 678, or 351#912345678 for numbers of other countries. A number in another format is refused with Please enter a valid MB WAY phone number (e.g. 912 345 678, or 351#912345678 for other countries). The module sends the payment request to the MB WAY app and sends the order e-mail. The order success page shows Confirm the payment request in your MB WAY app. with the masked phone number. Only a masked phone number is stored with the order. The payment description sent to ifthenpay is the name of your store (Stores > Configuration > General > General > Store Information > Store Name; if it is empty, the store name from Stores > All Stores) and the cart number. The same description is sent with Multibanco references.

Credit Card: the customer is sent to the ifthenpay card page, in Portuguese for a Portuguese store view and in English otherwise. The order e-mail is sent only after the payment is confirmed. 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, the cart and the card request of the cart; then the order is invoiced and the customer sees the standard order success page. If the return cannot be verified yet, a page shows Your card payment is being confirmed by ifthenpay. Check again in a moment; do not pay again. with a Check again link; the callback confirms the order as soon as it arrives. If the card payment fails or is cancelled, the order is cancelled (the stock goes back), the cart is restored and the customer sees 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. in the cart. Every card attempt of the cart is kept, so a payment made in an older tab is still recognised.

For every method, the order is marked paid only after ifthenpay confirms it, and the amount is checked to the cent against the order total. Magento then creates the invoice with the Multibanco reference, the MB WAY request ID or the card request ID as the transaction ID and sets the status from Order Status After Payment. For Credit Card the order e-mail is sent at this moment; for Multibanco and MB WAY the order e-mail was already sent with the payment details, and no second one is sent. If the order needs a manual review, the customer sees Your ifthenpay payment is under manual review. Do not pay again.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example 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., The payment service is temporarily unavailable. Please try again in a few minutes. or The ifthenpay payment could not be started. Please try again or choose another payment method. The ifthenpay answer is written to the log.

A Multibanco or MB WAY order waits in Pending Payment until ifthenpay reports the payment. Unpaid references and declined MB WAY requests do not cancel the order by themselves. The Magento cron cancels orders in Pending Payment after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings, 480 minutes by default). For Multibanco, set it long enough for your customers to pay. A payment that arrives after the order was cancelled is not invoiced; it is noted on the order for your review.

The module works with the standard Magento checkout. It offers one ifthenpay method per installation. It has no online refunds, 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. ifthenpay is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and is waiting for ifthenpay: a Multibanco reference or an MB WAY request was created, or the customer was sent to the card page. There is no invoice. A note says Awaiting ifthenpay payment with the method.

Processing or Complete: the payment was confirmed. The status follows Order Status After Payment. The invoice is created with the ifthenpay transaction ID, and a note shows the method, how the payment was confirmed (callback or signed return) and the transaction.

On Hold: ifthenpay reported a payment with a different amount or currency than the order (for example, the cart was changed after a card payment started). No invoice is created. The note explains it, and the customer is not asked to pay again. Check the payment in the ifthenpay backoffice, then complete the order manually or refund the customer there. A later correct payment for such an order does not complete it.

Canceled: the card payment failed or was cancelled, the payment could not be started, or the order was cancelled in Magento or by the cron. If ifthenpay reports a payment for a cancelled order (for example a Multibanco reference paid late), the order stays Canceled, no invoice is created and a note asks you to review the payment and the stock manually.

Closed: the order was fully refunded with a credit memo.

A second payment for an order or a cart that is already paid only adds a note to check for a duplicate payment in ifthenpay. Cancelled and refunded orders are never reopened. The notes are order comments that the customer does not see.

ifthenpay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when they are set, ifthenpay method, ifthenpay environment (sandbox or live), ifthenpay request and ifthenpay transaction. While the order waits for payment, it also shows the Multibanco entity, reference and amount or the masked MB WAY phone. The customer sees these payment details only while the order is in Pending Payment, and after that only the payment method title.

The Information tab of the order also shows ifthenpay payment history: every payment attempt of the order with Date, Method, Environment, Amount, Currency, Entity, Reference, Request ID, Masked phone and Status. It is shown also for old orders and while the module is disabled.

Refunds

Refunds through ifthenpay from Magento are not supported. Refund the customer in the ifthenpay backoffice, then create a credit memo in Magento with Refund Offline to record it. Refund Offline does not send money back. A full refund closes the order. A refunded (DEVOLVIDO) callback, and any other status reported by ifthenpay, only adds a note.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox ifthenpay Gateway is the first row of the VibeFox ifthenpay Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-ifthenpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

ifthenpay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the key of the selected Payment Method is saved. The cart must be in euros (EUR) and its total between 0.01 and 99,999.99 EUR. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the callback is not reaching your store or is rejected. 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, copied exactly as the Callback row shows it. The store must be reachable from the internet, not on localhost and not behind a login. For a card payment that was not confirmed, check the payment in the ifthenpay backoffice.

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. Click Save Config on the settings page and send the key to ifthenpay; ifthenpay retries the callback.

Callback answers 503 Busy or Retry: the same cart was being processed by another request at that moment, or an error occurred while the order was being updated. ifthenpay retries the callback.

Callback answers Order not found: the reference or request does not belong to a payment of this module, or the cart was ordered with another payment method.

Callback answers Invalid callback or 405: the request has none of the ifthenpay parameters or is not a GET request. The same answer appears when you open the callback URL in a browser without parameters; this is normal.

Callbacks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the callback URL too. Card payments are still confirmed by the signed return; for the others, ifthenpay retries the callback.

Why is a paid order On Hold? The amount or currency received was different from the order total. Read the order notes and the ifthenpay payment history, check the payment in the ifthenpay backoffice and complete the order manually or refund the customer.

A Multibanco order was cancelled before the customer paid: the Magento cron cancelled it after the Pending Payment Order Lifetime. Increase it in Stores > Configuration > Sales > Sales > Orders Cron Settings. For a payment that arrived later, read the order notes, check the stock and complete the order manually or refund the customer.

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. The order of that attempt is cancelled and the cart is restored.

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

There is no Refund button on the credit memo: the module has no online refunds. Refund in the ifthenpay backoffice and create the credit memo with Refund Offline.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_IfthenpayPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_IfthenpayPayment to remove the data, then bin/magento module:disable Vibefox_IfthenpayPayment, delete the folder app/code/Vibefox/IfthenpayPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the settings, the anti-phishing key and the log are removed too; after a re-install a new anti-phishing key is generated and must be sent to ifthenpay again. If it is No, the settings are kept for a re-install. The ifthenpay payment attempts and callback records are always kept, so callbacks for references issued before still find their orders after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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