VibeFox ECPay for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Currency: New Taiwan Dollar (TWD). ECPay charges TWD only, so the payment method is shown only when the customer's cart is in TWD. Add TWD in International > Localization > Currencies if your shop does not have it. Amounts are sent in whole TWD, because ECPay does not accept decimals: cart totals are rounded to the nearest dollar. Use 0 decimals for TWD prices 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 shop 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
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox ECPay Payment Gateway in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure 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.
On install the module creates two order statuses, Awaiting ECPay payment and ECPay payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; TWD must stay allowed for the module.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows an error when your shop has no TWD currency (ECPay is then not shown at checkout) or a warning when the default currency is not TWD (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.
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: the page does not save with an empty title.
Description: the text shown under the payment method at checkout. Default: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
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. under the payment method.
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.
Clear saved secrets: tick Hash Key or Hash IV and click Save to remove it. An empty field keeps the saved value.
Payment options
Enabled Payment Methods: the methods offered to customers. With more than one, the customer chooses at checkout. ATM, CVS and Barcode orders stay in Awaiting ECPay payment 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 shops share one ECPay account: give each shop its own prefix. Default: EC.
Payment notifications
ECPay sends payment results to your shop. This section shows the Notification URL. With friendly URLs it looks like https://your-shop/module/wcp_ecpay_payment_gateway/notify, possibly with a language code such as /en/. 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. The maintenance mode and the country restriction of your shop do 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, no order is created; check the payment in the ECPay back-office.
Advanced
Enable Logging: writes order IDs, trade numbers, amounts and ECPay return codes to logs/ecpay_p_debug.log.php in the module folder. The file cannot be opened from the web. 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 module removes its settings and the log. The ECPay payment records and the order statuses are always kept, so existing orders keep working after a re-install. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default ECPay (綠界)). With several methods enabled, the customer also picks Credit Card, ATM (Virtual Account), CVS (Convenience Store) or Barcode under Payment Method.
After confirming, the customer sees Redirecting to ECPay for payment. Please wait... and is sent to the ECPay payment page, with a Proceed to ECPay button in case the redirect does not start. The cart 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 shop language. No order exists yet at this point.
The order is created only after ECPay confirms it with a signed server notification. When the customer clicks the back-to-shop link on the ECPay page and the order already exists, the standard order confirmation 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 created 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.
For ATM, CVS and Barcode the customer first receives the payment details. The order is created in Awaiting ECPay payment, 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 confirmation page and in the customer's order details. When the customer pays, ECPay sends another notification and the order is marked paid. Payment instructions are not added to PrestaShop 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 to the redirect page, a new attempt is started. A cart can have up to 30 payment attempts. Once the cart has an order, it cannot be paid again through checkout; an awaiting ATM or CVS order is paid with the details already issued.
If the payment cannot be started, the customer stays at checkout with a short message, 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.
The module takes one-time payments on the ECPay page only. It has no refunds from PrestaShop, no saved cards, no subscriptions or periodic payments (定期定額), no installments, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, e-invoices or logistics, and no server-side status query: if your shop cannot receive the notification, check the payment in the ECPay back-office.
Orders
Order statuses
No order yet: the customer was sent to ECPay and has not paid, or the notification has not arrived yet. Only the cart exists.
Awaiting ECPay payment: 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: the payment was confirmed. The payment is recorded with the ECPay TradeNo as the transaction ID, and a note shows the TradeNo, the payment type, the amount and the trade number (with a test mode mark for sandbox payments).
ECPay payment on hold: ECPay reported a different amount or currency than the cart (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 the order had been cancelled (the payment is then recorded). The note explains it. Compare with the ECPay back-office and fulfil the order or refund the payment there.
Payment error: 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, refunded or cancelled 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.
ECPay payment block
The order page shows an ECPay payment block with every payment attempt of the order: the MerchantTradeNo with a Test mode badge for sandbox attempts, the method, the amount in TWD, the status, the ECPay TradeNo, the payment type and date and the ECPay return code. Below them are the ECPay notes of the order. For an order in ECPay payment on hold the block reminds you to compare it with the ECPay back-office.
Refunds
Refunds from PrestaShop are not available. Refund the payment in the ECPay back-office, then update the order in PrestaShop manually. The standard PrestaShop refund buttons of the order page do not send money back through ECPay.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox ECPay Payment Gateway is the first block on Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-ecpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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's cart is in TWD and, in live mode, the Merchant ID, Hash Key and Hash IV are set. The settings page shows a message in each of these cases. In Payment > Preferences check that the module is allowed for TWD, the customer's country and the customer's group.
The payment went through, but no order was created: the ECPay notification did not reach your shop (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 module 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 shop, for example when several shops share one ECPay account. Give each shop its own Order Prefix.
Notification answers 0|Retry: the cart was being processed by another notification at the same moment, or the order could not be created (for example, the module is disabled). 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 The order total is too small for ECPay.: the cart 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 ECPay payment on hold: read the notes in the ECPay payment block (see Order statuses), compare with the ECPay back-office, then fulfil the order or refund the payment there.
Developers: the hook actionEcpayPRequestParams lets another module change the parameters sent to ECPay; the merchant, trade number and amount cannot be changed by it.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox ECPay Payment Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete Data on Uninstall is on, the settings and the log are removed. If it is off, all settings are kept for a later re-install. The ECPay payment records and the order statuses Awaiting ECPay payment and ECPay payment on hold are always kept, so late notifications of old payments are still checked after a re-install. Existing orders keep their payment notes and transaction IDs.
ECPay is a trademark of its respective owner. This module is not affiliated with or endorsed by ECPay.