VibeFox ECPay for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active.

PHP: 8.0 or later.

Store currency: New Taiwan Dollar (TWD). ECPay charges TWD only, and the payment method is hidden when the store, or the order being paid, uses another currency. 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 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 site must be reachable from the internet over HTTP/HTTPS on port 80/443, so that ECPay can deliver payment notifications. Maintenance mode, 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_ecpay_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate. WooCommerce must be active.

3. Open the settings: WooCommerce > Settings > Payments > ECPay (綠界) > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Turn on Enable/Disable, choose the payment methods and keep Test Mode on for your first tests. In the sandbox you can pay with the ECPay test card 4311-9522-2222-2222 (any future expiry date, CVV 222, 3-D Secure code from the sandbox page).

6. For live payments enter the MerchantID, HashKey and HashIV (see Configuration) and untick Test Mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > ECPay (綠界). Above the fields the page shows an error when the store currency is not TWD (ECPay is then not shown at checkout) and 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.

General

Enable/Disable: Enable ECPay Payment turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: ECPay (綠界).

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: Enable sandbox/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.

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.

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 On hold until the customer pays. At least one method must be selected; if none is, Credit Card is enabled. 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. Useful when several shops share one ECPay account: give each shop its own prefix. Default: EC.

Payment notifications

ECPay sends payment results to your store. This section shows the notification URL. It looks like https://your-site/wc-api/ecpay_p_callback/. 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 maintenance mode, firewall or basic authentication in front of it.

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

Advanced

Enable Logging: Log payment events and API calls writes order IDs, trade numbers, amounts and ECPay return codes to WooCommerce > Status > Logs, source wcp_ecpay_payment_gateway. No keys or customer data are logged. Default: off.

Delete Data on Uninstall: Delete all plugin data when uninstalling. It removes all settings, logs and order meta of this plugin. Default: off.

Checkout

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. While test mode is on, the payment method shows TEST MODE — ECPay sandbox, no real money is charged.

After the order is placed, 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 order total is sent in whole TWD with the names and quantities of the items. The ECPay page opens in Traditional Chinese for Taiwanese and Hong Kong site languages, in Simplified Chinese, Korean or Japanese for those languages, and in English for all others.

The order is marked paid only after ECPay confirms it with a signed server notification. When the customer comes back to the order received page before the confirmation has arrived, the page shows We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: with a Pay button.

For ATM, CVS and Barcode the customer first receives the payment details. The order is put On hold, 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 thank-you page, in My account > Orders and in the Order on hold e-mail. When the customer pays, ECPay sends another notification and the order is marked paid.

Every visit of the payment page creates a new ECPay trade number, because ECPay rejects re-used numbers. So the Pay for order page and retries after a failed payment work, and notifications for any of these numbers are matched to the order. An order can have up to 30 payment attempts.

ECPay's own amount limits per method, for example for convenience store payments, are checked on the ECPay page, not at checkout.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments on the ECPay page only. It has no refunds from WooCommerce, 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 site cannot receive the notification, check the payment in the ECPay back-office.

Orders

Order statuses

Pending payment: the customer was sent to ECPay and has not paid yet, or the notification has not arrived yet.

On hold, waiting for payment: the customer chose ATM, CVS or Barcode and received the payment details. The order note shows the bank code and virtual account, the payment code or the barcodes and the deadline.

Processing: the payment was confirmed (the WooCommerce default; orders with only virtual downloadable products become Completed). The order note shows the ECPay TradeNo, the payment type, the amount and the trade number. The transaction ID is the ECPay TradeNo.

On hold after payment: ECPay reported a different amount or currency than the order, 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 order note explains it. Compare with the ECPay back-office and complete or refund the order manually.

Failed: ECPay reported that the latest payment attempt failed. The note shows the ECPay return code and message. The customer can try again.

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

Refunds

Refunds from WooCommerce are not available. Refund the payment in the ECPay back-office, then record the refund manually in WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > ECPay (綠界). Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

ECPay does not appear at checkout: check that the license is active, Enable/Disable is on, the store currency is TWD and, in live mode, the Merchant ID, Hash Key and Hash IV are set. The settings page shows an error in each of these cases.

The payment went through, but the order stays Pending payment: the ECPay notification did not reach your site (site down, firewall, maintenance mode, basic authentication). ECPay retries several times. You can also check the trade in the ECPay back-office and complete the order manually. Turn on Enable Logging to see the notifications the plugin received.

Notification answers 0|CheckMacValue verification failed: the Hash Key or Hash IV does not match your ECPay account. 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 shops share one ECPay account. Give each shop its own Order Prefix.

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.

Order is On hold with an amount mismatch note: the amount ECPay reports differs from the order total, for example the order was edited after the customer started paying. Compare with the ECPay back-office and complete or refund the order manually.

Order is On hold after a sandbox payment: the payment was made in test mode, but the store is now in live mode. No real money was collected. Check the order manually.

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

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The settings, the ECPay data stored on orders and the logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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