VibeFox iPay88 for Adobe Commerce — Aide

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.

iPay88 merchant account: the Merchant Code and Merchant Key are issued by iPay88 when your merchant account is activated. They are also shown in the iPay88 merchant portal. If you are not a merchant yet, apply on the iPay88 website. Keep the Merchant Key secret: it signs the payments. iPay88 has no separate sandbox, so there are no test keys.

Request URL: your website address must be registered with iPay88 as the request URL. Otherwise the iPay88 page shows "Permission not allow".

Currency: the order is charged in the currency the customer pays in. Malaysia — MYR, and USD, SGD, AUD, CAD, EUR, GBP, HKD, CNY, TWD, INR, IDR, PHP or THB if the multi-currency option is enabled on your iPay88 account; Philippines — PHP or USD; Indonesia — IDR; Thailand — THB. If the currency of the cart cannot be charged in your region, the payment method is hidden at checkout.

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-ipay88-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/Ipay88Payment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_Ipay88Payment 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.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox iPay88 Payment. 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 your iPay88 region, enter the Merchant Code and Merchant Key, set Enable to Yes and click Save Config. To check the setup, make a payment with Test mode set to Yes, then set it back to No.

The module adds the iPay88 payment method to the Magento checkout. It is off after installation (Enable = No, Test mode = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the iPay88 payment attempts and events. The Response URL and the Backend URL are sent with every payment.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox iPay88 Payment, 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.

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, the Response and backend URLs row shows these warnings when they apply: Enter the iPay88 Merchant Code and Merchant Key — until then the payment method is not shown at checkout.; The store currency ... cannot be charged in iPay88 region ... The payment method is hidden at checkout.; and, while test mode is on, TEST MODE: iPay88 has no separate sandbox. A fixed test amount ... is charged on the live gateway instead of the order total. Do not leave test mode enabled in a live store.

General

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

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

Description: shown in the payment method list at checkout when the customer selects iPay88. Default: Pay securely via iPay88 (credit card, online banking, e-wallet).

iPay88 account

iPay88 region: the country of your iPay88 merchant account. It selects the iPay88 payment page and the currencies that can be charged. The order is always charged in its own currency. Default: Malaysia.

Merchant Code: your iPay88 Merchant Code, for example M01234.

Merchant Key: your iPay88 Merchant Key. It signs payment requests and verifies iPay88 responses. Keep it secret. Magento stores the key 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; quotes and backslashes are kept.

Signature type: how payment requests are signed. Responses are verified in both formats, so payments started before a switch stay verifiable.

Payment method: pre-select one iPay88 payment method from the Malaysian PaymentId list, or leave Let the customer choose on the iPay88 page (default). The list includes Credit Card (MYR), FPX (Online Banking), Maybank2U, Alliance Online, AmBank, RHB Bank, Hong Leong Bank, CIMB Clicks, Web Cash, PayPal (MYR), Credit Card (PHP), Boost, Touch n Go eWallet, GrabPay and ShopeePay.

Reference prefix: optional. Added before the order ID in the iPay88 reference (RefNo), for example SHOP1-. Set a different prefix in every store that uses the same iPay88 account, so that a response of one store is never applied to an order of another. Letters, digits, "-" and "_", up to 10 characters. Other characters are removed when you save, and a prefix ending with a digit gets "-" at the end, because the order ID is read from the end of the RefNo. The page then shows Reference prefix: only letters, digits, "-" and "_" (max 10, not ending with a digit) are allowed. Normalized value: with the value that was saved; the other settings are saved as usual. If you move to Magento from another shop system with the same iPay88 account, set a prefix so that new references never repeat old order numbers.

Test mode: iPay88 has no separate sandbox. Test payments are real transactions on the live iPay88 page with a fixed small amount: 1.00 (IDR 10000) instead of the order total. The order is marked as paid when the test amount is received, and an order note says so. While test mode is on, the checkout shows TEST MODE: only a test amount of ... will be charged. iPay88 uses the live gateway. A payment started in test mode is always checked against the test amount, even if you turn test mode off before iPay88 answers. Do not leave it enabled on a live store. Default: No.

Response and backend URLs

The module sends both URLs with every payment, so there is nothing to configure. If iPay88 asks for them, copy them from this row. They are storefront addresses of the default store view (or of the store view selected in Scope) and look like https://your-store/wcpipay88payment/response/index/ (Response URL, the customer's return) and https://your-store/wcpipay88payment/backend/index/ (Backend URL, the server-to-server notification). The row also shows your website address, which must be registered with iPay88 as the request URL.

Both answers from iPay88 are checked the same way: the required fields, the signature made with your Merchant Key, and the reference of a payment this store started for the order. Responses without a valid signature are rejected and never change an order. The backend notification is answered with RECEIVEOK only after it was processed. Otherwise iPay88 sends it again. iPay88 reports these payment statuses:

Clear saved Merchant Key: set it to Yes and click Save Config to delete the saved Merchant Key. It goes back to No after saving.

Conditions

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

Payment from specific countries: offer iPay88 only for billing addresses in these countries.

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

Maximum order total: offer iPay88 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 currency of the selected region.

Advanced

Debug log: logs payment requests and iPay88 responses to var/log/ipay88_p_debug.log.php in the Magento folder. The file cannot be opened from the web. The Merchant Key, signatures, return tokens, e-mails and phone numbers are not logged. Errors and warnings are always logged, even when it is No. At 5 MB the log starts again and the previous one is kept as ipay88_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 and the log (see Uninstall). Orders and the iPay88 payment records always stay. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default iPay88) and sees the iPay88 logo, the description and You will be redirected to iPay88 to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The next page shows Redirecting to iPay88 payment gateway... and Please do not close this window. while a form is sent to the iPay88 payment page of your region. Without JavaScript the customer clicks Pay Now. The module passes the order total in the order currency (the test amount in test mode), the product names, the order number, the customer's name, e-mail and phone. On the iPay88 page the customer pays by card, FPX online banking, e-wallet or another method your account offers.

The order is marked paid only after iPay88 confirms it with a signed response, either on the customer's return or by the backend notification. Magento then creates the invoice with the iPay88 TransId as the transaction ID, the order becomes Processing, and the order e-mail and the invoice e-mail are sent as set up in your store. The customer sees the standard order success page with Your iPay88 payment has been received. For a pending payment the page shows Your payment is pending confirmation from iPay88. We will update your order as soon as the payment is confirmed. For an order on hold it shows We have received a payment notification from iPay88 and are reviewing it. We will contact you if anything is needed. Otherwise it shows The payment was not completed. Please contact us. If the customer returns in another browser, the store home page opens.

If the result has not arrived yet when the customer returns, a page shows We have not received the payment confirmation from iPay88 yet. If you completed the payment, your order will be updated shortly. with Check again and Back to checkout. Back to checkout cancels the waiting order and restores the cart.

If the payment failed or was cancelled, the order is cancelled (the stock goes back), the cart is restored and the customer sees in the cart The payment was not completed: with the iPay88 reason, followed by You can try again or choose another payment method. If the response cannot be verified, the customer sees The payment response could not be verified. If you completed the payment, please contact us with your order number — the payment will be checked manually. with a Return to the store link.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees in the cart This payment method is temporarily unavailable. Please choose another payment method. (keys missing or a zero total) or iPay88 cannot accept payments in ... Please choose another payment method. (currency not chargeable in the region). If another order of the same cart is already paid or waiting for iPay88, no second payment form is built: the new order is cancelled and the customer sees Your cart already has a payment for order #... on the home page.

The Magento cron cancels orders in Pending Payment after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). 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 and takes one-time payments only. It has no online refunds, saved cards, subscriptions, pre-authorisation and capture, or card fields on your site. It does not re-query iPay88 for the payment status: orders are updated only by the iPay88 response and the backend notification. iPay88 is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the customer was sent to iPay88 and no result has arrived yet, or iPay88 reported the payment as pending (status 6). There is no invoice. For a pending payment a note says so and the order e-mail is sent. The order is invoiced when iPay88 confirms the payment, or cancelled if it fails.

Processing: iPay88 reported a successful payment with the expected amount and currency. The invoice is created with the iPay88 TransId as the transaction ID. A note shows the TransID, PaymentID, amount and currency. In test mode a second note says that the test amount was charged instead of the order total.

On Hold: iPay88 reported a successful payment with a different amount or currency than the order. The order was NOT marked as paid and no invoice was created. The note explains it, and the order e-mail is sent. Check the payment in the iPay88 portal, then fulfil the order manually or refund the payment there. The same answer repeated changes nothing; a later correct payment with another TransId releases the hold and invoices the order.

Canceled: the payment failed or was cancelled, the payment could not be started, or the order was cancelled in Magento or by the cron. If iPay88 reports a successful payment for a cancelled order, the order stays Canceled, no invoice is created and a note asks you to check the payment and fulfil or refund it in the iPay88 portal.

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

A paid or refunded order is never changed by a later answer. If another successful payment arrives for it or for another order of the same cart, a note asks you to check it in the iPay88 portal and refund it if it is a duplicate. A failed answer never changes a paid, held or cancelled order. The notes are order comments that the customer does not see.

iPay88 payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when they are set, iPay88 reference, iPay88 TransId, iPay88 PaymentId, iPay88 AuthCode, iPay88 region, iPay88 requested amount, iPay88 paid amount, iPay88 reported amount (for a payment that did not match) and iPay88 mode for test payments. The customer sees only the payment method title.

The Information tab of the order also shows iPay88 payment history: every payment attempt of the order with Created, Attempt, Reference, Region, Test mode, Signature type, Requested, Received, TransId, PaymentId, AuthCode, iPay88 status, Status and Error. It is shown also for old orders and while the module is disabled.

Refunds

Refunds through iPay88 from Magento are not supported. Refund the payment in the iPay88 merchant portal, 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.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox iPay88 Payment is the first row of the VibeFox iPay88 Payment 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-ipay88 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, iPay88 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

iPay88 does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the Merchant Code and Merchant Key are saved, and that the cart currency can be charged in the selected iPay88 region. The settings page shows a warning when something is missing. 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: neither the customer's return nor the backend notification reached your store with a valid signature. Look at the Log field: errors are always logged. Check that the Merchant Key is exactly the one iPay88 gave you, for the website of the store, and that your server accepts requests from iPay88 at the Backend URL shown in the settings. The store must be reachable from the internet, not on localhost and not behind a login.

The iPay88 page shows "Permission not allow": your website address is not registered with iPay88 as the request URL. Ask iPay88 to register the address shown in the Response and backend URLs row.

Backend notification answers BAD SIGNATURE: the signature does not match the Merchant Key. Check the Merchant Key. Nothing was changed.

Backend notification answers NOT CONFIGURED: the Merchant Code or Merchant Key is not set, so the response cannot be verified. iPay88 sends the notification again.

Backend notification answers UNKNOWN ORDER: no iPay88 payment was started for this reference in this store, for example because another store with the same account uses no Reference prefix or the same one.

Backend notification answers RETRY: the order was being confirmed by the customer's return at the same moment, or an error occurred while the order was being updated. iPay88 sends the notification again.

The Backend URL shows METHOD NOT ALLOWED in the browser: this is normal. The URL accepts only signed POST requests from iPay88.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the Backend URL and the Response URL too. iPay88 sends the backend notification again; to let it through during maintenance, allow the iPay88 servers in the standard Magento maintenance settings or your server rules.

The order is On Hold: iPay88 reported a payment that does not match the order. Read the order notes and the iPay88 payment history, check the payment in the iPay88 portal, then complete the order manually or refund the payment.

The customer sees "iPay88 cannot accept payments in" a currency: the cart currency cannot be charged in the selected region. On iPay88 Malaysia, currencies other than MYR also need the multi-currency option on your iPay88 account.

Real customers are charged only 1.00: Test mode is Yes. Set it to No.

There is no Refund button on the credit memo: the module has no online refunds. Refund in the iPay88 merchant portal 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_Ipay88Payment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the settings and the log are removed too. If it is No, the settings are kept for a re-install. The iPay88 payment attempts and events are always kept, so answers for payments started before still find their orders after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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