VibeFox ECPay 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: New Taiwan Dollar (TWD). ECPay charges TWD only, so the payment method is shown only when the customer checks out in TWD. Add TWD with the code TWD in System > Localisation > Currencies if your store does not have it. Amounts are sent in whole TWD, because ECPay does not accept decimals: order totals are rounded to the nearest dollar. Use 0 decimals for TWD to avoid rounding.

ECPay account: for live payments you need the MerchantID, HashKey and HashIV of your ECPay merchant account, from the ECPay merchant back-office (vendor.ecpay.com.tw). For testing no ECPay account is needed.

Site access: your store must be reachable from the internet over HTTP/HTTPS on port 80/443, so that ECPay can deliver payment notifications. A firewall or basic authentication in front of the site blocks them.

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_ecpay_payment_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_ecpay_payment_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_ecpay_payment_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 ECPay Payment Gateway 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. Turn on Enable/Disable, choose the payment methods and keep Test Mode on for your first tests. Click Save.

5. For live payments enter the Merchant ID, Hash Key and Hash IV (see Configuration), turn off Test Mode and click Save.

OpenCart 4

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

4. Enter the license key and the settings as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Payment notifications).

A new install starts with the payment method turned off and test mode on. The notification URL is sent with every payment, so nothing has to be configured in ECPay.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox ECPay Payment Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page shows an error when the default currency of your store is not TWD and there is no enabled TWD currency (ECPay is then not shown at checkout), or a warning when TWD is only a second currency (ECPay is then shown only to customers who pay in TWD). It shows an error when live mode has no MerchantID, HashKey and HashIV. While test mode is on, it warns that payments go to the ECPay sandbox with the public test merchant 3002607, that no money is collected, and that anyone who knows the public sandbox keys could confirm test orders, so test mode must be off before you accept real orders. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty (at most 128 characters), Sort Order must be a whole number and Total a number of 0 or more; otherwise nothing is saved. Other corrections are saved with a message above the settings (see the fields below).

ECPay (綠界)

Enable/Disable: Enable ECPay Payment 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: ECPay (綠界). Required.

Description: the text shown to the customer at the Confirm Order step. Default: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).

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

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

ECPay account

Find your MerchantID, HashKey and HashIV in the ECPay merchant back-office (vendor.ecpay.com.tw) under System development management > System integration settings (系統開發管理 > 系統介接設定).

Test Mode: sends payments to the ECPay sandbox (payment-stage.ecpay.com.tw) with the public ECPay test merchant 3002607. No real money. The credentials below are used only when test mode is off. Default: on. While it is on, customers see TEST MODE — ECPay sandbox, no real money is charged. at the Confirm Order step.

Merchant ID: your ECPay Merchant ID (production). Ignored in test mode.

Hash Key: your ECPay Hash Key (production). Ignored in test mode.

Hash IV: your ECPay Hash IV (production). Ignored in test mode.

Spaces and line breaks in pasted credentials break every signature, so they are removed when you save, and the page tells you about it. A saved Hash Key and Hash IV 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 value, tick Clear the saved value on save under the field and click Save.

Payment options

Enabled Payment Methods: the methods offered to customers. With more than one, the customer chooses at the Confirm Order step. ATM, CVS and Barcode orders stay in the awaiting status until the customer pays. At least one method must be selected; if none is, Credit Card is enabled and the page tells you. Default: Credit Card.

Default Payment Method: the pre-selected method. It must be one of the enabled methods; otherwise the first enabled method is used. Default: Credit Card.

Order Prefix: the prefix of the ECPay trade number (MerchantTradeNo), up to 5 letters or digits. Other characters are removed when you save, with a message. Useful when several stores share one ECPay account: give each store its own prefix. Default: EC.

Payment notifications

ECPay sends payment results and the ATM, CVS and barcode details to your store. This section shows the Notification URL. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_ecpay_payment_gateway/notify, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_ecpay_payment_gateway/payment/wcp_ecpay_payment_gateway.notify. The URL is sent with every payment, so nothing has to be configured in ECPay, but it must be reachable from the internet on port 80/443 with no firewall or basic authentication in front of it. Maintenance mode does not block it.

Each notification is checked by its CheckMacValue signature with the keys of the environment (test or live) in which the payment was started, and by the MerchantID of that payment. Notifications without a valid signature are rejected, and ECPay sends them again. Without the notification, the order gets no status; check the payment in the ECPay back-office.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only from the signed ECPay notification. A failed or abandoned card payment leaves it without a status, and the customer can pay again. Each field below lists your OpenCart order statuses.

Payment accepted: the status when ECPay confirms the payment with the expected amount. Default: Processing.

Awaiting ECPay payment: the status when the customer received an ATM virtual account, a CVS payment code or barcodes and pays later at the ATM or store. Default: Pending.

ECPay payment on hold: the status when ECPay reports another amount or currency, a sandbox payment arrives in live mode, or the payment arrives after the order status was changed (for example cancelled). The order 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.

Payment error: the status when the latest ATM, CVS or barcode payment of an awaiting order failed. Default: Failed.

Advanced

Enable Logging: writes order IDs, trade numbers, amounts and ECPay return codes to ecpay_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to ecpay_p_debug.old.log.php. No keys or customer data are logged. Errors are always logged, even when this 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 its settings and the log. The ECPay payment records are always kept, so existing orders keep working after a re-install. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Hash Key and Hash IV are not exported.

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

Checkout

At the Payment Method step the customer chooses the payment method (by default ECPay (綠界)). At the Confirm Order step the customer sees your description and the note You will be redirected to the ECPay payment page to complete the payment. With several methods enabled, the customer also picks Credit Card, ATM (Virtual Account), CVS (Convenience Store) or Barcode under Payment 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; the choice of the ECPay method is shown above that button.

When the customer clicks Confirm Order, the page shows Redirecting to ECPay for payment. Please wait... and sends the customer to the ECPay payment page. The order total is sent in whole TWD with the names and quantities of the products. The ECPay page opens in Traditional Chinese for Taiwanese and Hong Kong languages, in Simplified Chinese, Korean or Japanese for those languages, and in English for all others, following the customer's store language.

The order is marked paid only after ECPay confirms it with a signed server notification. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update. When the customer clicks the back-to-store link on the ECPay page and the order already has a status, the OpenCart order success page opens. It shows Your ECPay payment has been received. for a paid order, Your ECPay payment was received and is being reviewed by the store. for an order on hold, and the payment instructions for an awaiting ATM, CVS or Barcode order. If the notification has not arrived yet, a Payment confirmation page shows We have not received a payment confirmation from ECPay for this order yet. Your order will be confirmed as soon as ECPay confirms the payment. with the buttons Check again and Back to checkout. If ECPay reported that the payment failed, the customer is back at checkout with The payment was not completed. You can try again or choose another payment method. The cart is kept. On OpenCart 4 these messages are shown above the checkout page.

For ATM, CVS and Barcode the customer first receives the payment details. The order gets the Awaiting ECPay payment status, and the bank code and virtual account, the convenience store payment code or the barcodes, the amount and the Pay before date are shown under ECPay payment instructions on the order success page and, for a logged-in customer, in the order information of the customer account. When the customer pays, ECPay sends another notification and the order is marked paid. Payment instructions are not added to OpenCart e-mails.

Every attempt creates a new ECPay trade number, because ECPay rejects re-used numbers. So retries after a failed payment work, and if the customer goes back in the browser and clicks Confirm Order again, a new attempt is started. A cart can have up to 30 payment attempts. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 updates the order of the checkout, so a retry pays the same order with a new trade number. When another order of the same cart is already paid or awaits its ATM or CVS payment, the customer goes to the success page and no new payment is started.

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 its ATM or CVS payment failed or you cancelled it), the customer is sent back to the checkout with Your previous order was cancelled or its payment failed. Please confirm the order again., and the next Confirm Order pays a new order of the cart. If that order is already paid (or awaits its ATM or convenience store payment) but the cart has changed since, including a new quantity, the message is Your previous order is already paid (or awaits its ATM / convenience store payment). Please confirm the order again: the cart will be paid with a new order. A paid order is never shown as paid for a different 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 order total is too small for ECPay. when the total is below 1 TWD after rounding. ECPay's own amount limits per method are checked on the ECPay page, not at checkout.

Notifications of payments already started are accepted even if you turn the payment method off, and the customer still sees the payment instructions of orders already placed.

The extension takes one-time payments on the ECPay page only. It has no refunds from OpenCart, no saved cards, no subscriptions or periodic payments (定期定額), no installments, Apple Pay, e-invoices or logistics, and no server-side status query: if your store cannot receive the notification, check the payment in the ECPay back-office.

Orders

Order statuses

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

Awaiting ECPay payment (default Pending): the customer chose ATM, CVS or Barcode and received the payment details. The note shows the bank code and virtual account, the payment code or the barcodes and the deadline.

Payment accepted (default Processing): the payment was confirmed. A note shows the ECPay TradeNo, the payment type, the amount and the trade number (with a test mode mark for sandbox payments).

ECPay payment on hold (default Pending): ECPay reported a different amount or currency than the order (for example, the cart was changed in another tab after the payment started), a sandbox payment arrived after you switched to live mode (no real money was collected), or the payment arrived after you had changed the order status, for example cancelled it. The note explains it. Compare with the ECPay back-office and fulfil the order or refund the payment there.

Payment error (default Failed): ECPay reported that the latest ATM, CVS or Barcode payment of an awaiting order failed. The note shows the ECPay return code and message.

Repeated notifications are ignored. A paid order is never reopened by a late failure. A second payment for an order that is already paid, for example from two browser tabs, is recorded as a note once, so you can refund it in the ECPay back-office. Simulated payments started from the ECPay back-office are noted only and never mark an order paid, because ECPay collects no money for them.

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

VibeFox ECPay Payment Gateway tab

In Sales > Orders open an order paid with ECPay. At the bottom of the order page, next to History and Additional, the VibeFox ECPay Payment Gateway tab lists every payment attempt of the order: the MerchantTradeNo with a Test mode label for sandbox attempts, the method, the amount in TWD, the status, the ECPay TradeNo, the payment type and date, the ECPay return code and the start date. Below them are the ECPay notes of the order. For an order in the on-hold status the tab reminds you to compare it with the ECPay back-office. The tab is read-only and is shown to users who have access to the extension.

Refunds

Refunds from OpenCart are not available. Refund the payment in the ECPay back-office, then update the order status in OpenCart manually. Product returns in Sales > Returns do not send money back through ECPay.

License key

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

ECPay does not appear at checkout: check that the license is active, Enable/Disable is on, the customer checks out in TWD and, in live mode, the Merchant ID, Hash Key and Hash IV are set. The settings page shows a message for the currency and the live credentials. 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: the ECPay notification did not reach your store (site down, firewall, basic authentication). ECPay retries several times. You can also check the trade in the ECPay back-office. Turn on Enable Logging to see the notifications the extension received; rejected notifications are logged as errors in any case.

Notification answers 0|CheckMacValue verification failed: the Hash Key or Hash IV does not match your ECPay account, or the payment was started in the other environment. Copy them again from the ECPay back-office.

Notification answers 0|MerchantID mismatch: the notification belongs to another ECPay merchant than the one the payment was started with.

Notification answers 0|Order not found: the trade number was not issued by this store, for example when several stores share one ECPay account. Give each store its own Order Prefix.

Notification answers 0|Retry: the order was being processed by another notification at the same moment, or the order status could not be set. ECPay sends the notification again. Turn on Enable Logging to see the reason.

The notification URL shows 0|Method not allowed in the browser: this is normal. The URL accepts only requests from ECPay.

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.

The customer sees The order total is too small for ECPay.: the order total is below 1 TWD after rounding and cannot be paid with ECPay.

The customer sees Too many payment attempts for this order: the cart reached 30 payment attempts. Ask the customer to start a new cart.

Order is in the on-hold status: read the notes in the VibeFox ECPay Payment Gateway tab (see Order statuses), compare with the ECPay back-office, then fulfil the order or refund the payment there.

For developers: before the payment form is sent to ECPay, the extension triggers the OpenCart event ecpay_p_request_params with the parameters and the order; the merchant, trade number and amount cannot be changed by it.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox ECPay Payment 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 events of the extension are removed too (on OpenCart 4 also its startup action, which lets the notification through in maintenance mode). If Delete Data on Uninstall is on, the other settings (title, description, test mode, credentials, payment options, logging) and the log are removed. If it is off, they are kept for a later re-install. The ECPay payment records are always kept, so late notifications of old payments are still checked 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 ECPay Payment Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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