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

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: 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 customer's checkout currency 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 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_ipay88_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_ipay88_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_ipay88_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 iPay88 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. Choose your iPay88 region, enter the Merchant Code and Merchant Key, turn on Enable/Disable and click Save.

5. To check the setup, make a payment with Test mode on, then turn test mode off.

OpenCart 4

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

4. Enter the license key and the iPay88 settings as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the response and backend URLs are different (see Response and backend URLs).

A new install starts with the payment method turned off. The response and backend URLs are sent with every payment, so nothing has to be set up for them at iPay88.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox iPay88 Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page shows Enter the iPay88 Merchant Code and Merchant Key — until then the payment method is not shown at checkout. while a key is missing, a warning when the default currency of the store cannot be charged in the selected region (the payment method is then hidden at checkout for this currency), and a warning while test mode is on. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be longer than 128 characters, Sort Order must be a whole number, Total a number of 0 or more, and the selected geo zone and order statuses must exist. Otherwise nothing is saved and the error names the field. The iPay88 fields never block saving.

iPay88

Enable/Disable: Enable iPay88 Payment Gateway 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. Default: iPay88. Up to 128 characters; if you leave it empty, customers see iPay88.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely via iPay88 (credit card, online banking, e-wallet).

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

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

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. Spaces at the start and the end are removed when you save. The saved key is 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 the saved key, tick Clear the saved Merchant Key on save and click Save.

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

Payment

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 number 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 number is read from the end of the RefNo. The page then warns you with the value that was saved.

Test mode: charges a fixed test amount instead of the order total. iPay88 has no separate sandbox: test payments are real transactions on the live iPay88 page with a small amount (1.00; IDR 10,000). The order is marked as paid when the test amount is received, and the order note says so. While test mode is on, customers see TEST MODE: only a test amount of ... will be charged. at the Confirm Order step. A payment started in test mode is always checked against the test amount, even if you turn test mode off before iPay88 answers. Never leave test mode on in a live store. Default: off.

Response and backend URLs

The extension sends both URLs with every payment, so there is nothing to configure. If iPay88 asks for them, copy them from this section. On OpenCart 3 they look like https://your-store/index.php?route=extension/payment/wcp_ipay88_payment/back (Response URL, the customer's return) and https://your-store/index.php?route=extension/payment/wcp_ipay88_payment/backend (Backend URL, the server-to-server notification), on OpenCart 4 like https://your-store/index.php?route=extension/wcp_ipay88_payment/payment/wcp_ipay_88payment.back and https://your-store/index.php?route=extension/wcp_ipay88_payment/payment/wcp_ipay_88payment.backend. The section 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 this 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. It 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 signed backend notification and the customer's return through. iPay88 reports these payment statuses:

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after iPay88 has sent a correctly signed response. A failed or cancelled payment leaves the order without a status; the customer goes back to the checkout with the cart kept. Each field below lists your OpenCart order statuses.

Order Status After Payment: a successful payment (iPay88 status 1) with the expected amount and currency. Default: Processing.

Awaiting Payment Status: a pending payment (status 6), for example an ATM or virtual account transfer the customer has not made yet. The order moves to the status after payment when iPay88 confirms it. Default: Pending.

On Hold (Review) Status: iPay88 reported a successful payment, but with another amount or currency than the order, or for an order that had been cancelled. A note shows the details; the order is not marked as paid. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Failed Payment Status: a pending payment (status 6) that iPay88 then reported as failed (status 0). Default: Failed.

Cancelled Order Status: the status your store uses for cancelled orders. A payment received for such an order puts it in the review status instead of marking it as paid. The extension never sets this status. Default: Canceled.

Advanced

Debug log: logs payment requests and iPay88 responses to ipay88_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. No personal data, Merchant Key or signatures are logged. Errors and warnings are always logged, even when the switch is off. 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 settings and the log. Orders and the iPay88 payment records are never deleted, so a late response of an old payment is still handled after a re-install. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The Merchant Key is not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved Merchant Key is kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default iPay88). At the Confirm Order step the customer sees your description. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the step shows Redirecting to iPay88 payment gateway... and Please do not close this window. while a signed form is sent to the iPay88 payment page of your region. If the browser does not send it automatically, the customer clicks Pay Now. The extension passes the order total in the order currency (the test amount in test mode), the product names, 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.

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. By default OpenCart 4 does not ask for a telephone at checkout, but iPay88 requires one: if the order has no phone, the confirmation step shows a required Phone field with iPay88 requires the contact number of the payer. Without a number the customer sees iPay88 requires a phone number. Please enter your phone number and try again. The number entered is kept for the next attempt.

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. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update. After a successful payment the customer sees the OpenCart 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 review it shows We have received a payment notification from iPay88 and are reviewing it. We will contact you if anything is needed. When a pending payment is confirmed or fails later, OpenCart notifies the customer of the new status.

If the order is being confirmed by the backend notification at the same moment, the customer sees We have not received the payment confirmation from iPay88 yet. If you completed the payment, your order will be updated shortly. with the buttons Check again and Back to checkout.

If the payment failed or was cancelled, the order stays without a status and the cart is kept. The customer is back at checkout with The payment was not completed: and the iPay88 reason, followed by You can try again or choose another payment method. On OpenCart 4 this message is shown above the checkout page. OpenCart 3 creates a new order, and so a new RefNo, every time the Confirm Order step is shown; OpenCart 4 updates the order of the checkout, so the customer pays the same order again. A new attempt of the same order uses the same RefNo. 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 button.

If the payment cannot be started, the customer stays at the Confirm Order step with 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). One cart is paid only once: if another order of the same cart is already paid or waiting for a pending payment, no second payment form is built and the customer is sent to the order success page. 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 a pending transfer failed or you cancelled the order), 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, the message is Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. In both cases the next Confirm Order pays a new order of the cart.

The extension takes one-time payments only. It has no refunds from OpenCart, 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.

Orders

Order statuses

No status (missing order): the customer was sent to iPay88 and no result has arrived yet, or the payment failed. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): iPay88 reported a successful payment with the expected amount and currency. 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.

Awaiting Payment Status (default Pending): iPay88 reported the payment as pending. The order moves to Order Status After Payment when iPay88 confirms it, or to Failed Payment Status if it fails.

Failed Payment Status (default Failed): a pending payment then failed. The note shows the iPay88 reason. The customer can place a new order.

On Hold (Review) Status (default Pending): iPay88 reported a successful payment with a different amount or currency than the order, or the payment arrived after the order had been cancelled. The order was NOT marked as paid. The note explains it. Check the payment in the iPay88 portal and fulfil the order or refund the payment.

A paid or completed 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, cancelled or reviewed order. Repeated answers add nothing new.

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

VibeFox iPay88 Payment tab

In Sales > Orders open an order paid with iPay88. At the bottom of the order page, next to History and Additional, the VibeFox iPay88 Payment tab shows the RefNo, TransId, Status, the Requested amount, the Amount received, the PaymentId, the AuthCode, the Error and the Region, a TEST MODE badge for test payments and the iPay88 notes of the order. The tab is shown to users who have access to the extension.

Refunds

Refunds are not sent to iPay88 from OpenCart. Refund the payment in the iPay88 merchant portal, then record the refund in OpenCart manually.

License key

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

iPay88 does not appear at checkout: check that the license is active, Enable/Disable is on, the Merchant Code and Merchant Key are entered, and the customer's checkout currency can be charged in the selected iPay88 region. The settings page shows a warning when something is missing. 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: 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 and that your server accepts requests from iPay88 at the Backend URL shown in the settings.

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 section.

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 on 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 (or another order of the same cart) was being confirmed by the customer's return or another notification at the same moment, or the order status could not be set. iPay88 sends the notification again.

The Backend URL shows BAD REQUEST in the browser: this is normal. The URL accepts only signed requests from iPay88.

The order is in the On Hold (Review) Status: iPay88 reported a payment that does not match the order, or the order had been cancelled. Read the notes in the VibeFox iPay88 Payment tab and check the payment in the iPay88 portal, then complete the order or refund the payment.

The customer sees "iPay88 cannot accept payments in" a currency: the checkout 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.

The customer sees This payment method is not available. Please reload the checkout page.: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

Real customers are charged only 1.00: Test mode is on. Turn it off.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox iPay88 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 iPay88 responses through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, region, Merchant Code and Key, signature type, payment method, prefix, test mode, debug log switch) and the log are removed. If it is off, they are kept for a later re-install. The iPay88 payment records of orders are always kept. Orders are never deleted and 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 iPay88 Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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