VibeFox ECPay for Adobe Commerce — Ajuda
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, with the mbstring and JSON extensions.
Currency: New Taiwan Dollar (TWD). ECPay charges TWD only, so the payment method is shown only when the customer's cart is in TWD. If TWD is not the base currency of your store, allow it in Stores > Configuration > General > Currency Setup and set its rate in Stores > Currency Rates. ECPay does not accept decimals, so the order total is sent rounded to whole TWD. Use whole TWD amounts: a paid order whose total has cents goes On Hold for review without an invoice (see Orders and refunds).
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 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-ecpay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/EcpayPayment/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_EcpayPayment 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 ECPay Payment Gateway. 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. Set Enable to Yes, choose the payment methods, keep Test mode on Yes for your first tests and click Save Config. For live payments enter the MerchantID, HashKey and HashIV (see Configuration), set Test mode to No and click Save Config.
The module adds the ECPay (綠界) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables, for the ECPay payment attempts and for the notifications already applied.
Configuration
All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox ECPay Payment Gateway, 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. Amounts are entered with a dot, for example "9.99".
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a number, 0 or greater.).
Some values are corrected when you save, with a message: spaces and line breaks are removed from the MerchantID, HashKey and HashIV, because they break every signature (ECPay: Spaces were removed from …); other characters than letters and digits are removed from Order prefix; when no payment method is selected, Credit Card is enabled.
When Enable is Yes, saving also checks the settings of the Default Config. In test mode Magento shows ECPay: TEST MODE uses public sandbox credentials; anyone knowing them could confirm test orders. Turn test mode off before accepting real orders. In live mode without keys it shows ECPay: Live mode needs MerchantID, HashKey and HashIV. When the store currency is not TWD it shows ECPay: TWD only; the method is hidden for other currencies.
ECPay notification URL
The row under the license block shows the Notification URL (ReturnURL and PaymentInfoURL). It is the storefront address of the default store view and looks like https://your-store/wcpecpaypaymentgateway/notify/index/. The URL is sent to ECPay with every payment (for each order, with the address of the order's store view), so nothing has to be configured in ECPay. It must be reachable from the internet on port 80/443, with no firewall or basic authentication in front of it. While Enable is Yes, the row also shows the same reminders as above: test mode, missing live keys, a store currency other than TWD.
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 stays in Pending Payment; check the payment in the ECPay back-office.
General
Enable: shows or hides ECPay at checkout. Default: No.
Title: the payment method name customers see at checkout. It is also stored in the order, so old orders keep the title they were placed with. Default: ECPay (綠界). Required, at most 128 characters.
Description: shown in the payment method list at checkout. Default: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
Sort Order: the position among the payment methods at checkout. A whole number. Default: 0.
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: when Yes, payments go to the ECPay sandbox (payment-stage.ecpay.com.tw) with the public ECPay test merchant 3002607. No real money. The keys below are used only when test mode is No. Default: Yes. While it is on, customers see TEST MODE: public sandbox merchant; no real money is charged. under the payment method.
MerchantID: your ECPay MerchantID (production). Ignored in test mode.
HashKey: your ECPay HashKey (production). Ignored in test mode.
HashIV: your ECPay HashIV (production). Ignored in test mode.
Magento stores the HashKey and HashIV encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved value, clear the field and click Save Config.
Options
Payment methods: the ECPay methods offered to customers. Default: Credit Card.
ATM, CVS and Barcode orders stay in Pending Payment until the customer pays (see Checkout). At least one method must be selected; if none is, Credit Card is enabled and Magento shows ECPay: Select at least one payment method — Credit Card was enabled.
Default payment method: the method pre-selected at checkout. If it is not one of the enabled methods, 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 the message ECPay: Order Prefix may contain only letters and digits (max 5); other characters were removed. Useful when several stores share one ECPay account: give each store its own prefix. Default: EC.
Limits
Payment from Applicable Countries: All Allowed Countries offers ECPay for every country your store allows, Specific Countries only for the countries below.
Payment from Specific Countries: offer ECPay only for billing addresses in these countries.
Minimum Order Total: offer ECPay only from this order total, in the base currency of your store. 0 or empty means no minimum. Default: 0.
Maximum Order Total: offer ECPay only up to this order total, in the base currency. 0 or empty means no maximum. Default: 0.
ECPay's own amount limits per method are checked on the ECPay page, not at checkout.
Advanced
Enable Logging: switches the log var/log/ecpay_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys and e-mail addresses are masked. Errors are always logged, even when this switch is No: rejected notification signatures, failed processing of a notification and order e-mails that could not be sent. Default: No.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The ECPay payment records always stay. Default: No.
Log: the last row of the group shows the size and the latest entries of the log. Click Clear log to empty it.
Checkout
At the payment step the customer chooses the payment method (by default ECPay (綠界)) and sees the description, the note You will be redirected to ECPay to complete the payment securely. and the list ECPay payment method with the enabled methods: Credit Card, ATM virtual account, Convenience store code or Barcode.
After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The customer sees You are being redirected to ECPay. and is sent to the ECPay payment page, with a Pay via ECPay button in case the redirect does not start. 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 locales, in Simplified Chinese, Korean or Japanese for those locales, and in English for all others, following the locale of the store view.
The order is marked paid only after ECPay confirms it with a signed server notification. Magento then creates the invoice with the ECPay TradeNo as the transaction ID, sets the order to Processing and sends the order e-mail. When the customer clicks the back-to-store link on the ECPay page, the standard order success page opens. A customer who comes back in another browser lands on the home page. If the notification has not arrived yet, the customer sees a simple page ECPay payment pending with Your payment has not been confirmed. This page does not confirm a payment. and the links Check again and Cancel this order and return to checkout. Cancelling cancels the order (the stock goes back) and restores the cart. The page warns that an ECPay payment link may still accept payment after the order is cancelled.
For ATM, CVS and Barcode the customer first receives the payment details. ECPay sends them to the store, the order stays in Pending Payment and Magento sends the order e-mail. The details (bank code and virtual account, the convenience store payment code or the barcodes, and the payment deadline) are shown under ECPay payment instructions on the order success page and in the payment information of the order in the customer's account, with the ECPay field names BankCode, vAccount, PaymentNo, Barcode1 to Barcode3 and ExpireDate. When the customer pays, ECPay sends another notification and the order is invoiced.
If ECPay reports that the latest payment of an order failed, the order is cancelled. A customer who returns from ECPay in the same browser gets the cart back and can try again or choose another payment method.
Every attempt creates a new ECPay trade number, because ECPay rejects re-used numbers. 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 a payment for the cart has been recorded, or ATM, CVS or Barcode details have been issued, no new payment is started for it.
If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example The order total is too small for ECPay. when the total is below 1 TWD after rounding, ECPay accepts payments in New Taiwan Dollars (TWD) only., Too many payment attempts for this order. Please contact the store. or This cart has already been paid. Please contact the store.
Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). ATM, CVS and Barcode orders wait in Pending Payment until the customer pays, so set this lifetime longer than the payment deadline (ExpireDate) that ECPay gives. If ECPay reports a payment for a cancelled order, the order stays Canceled, no invoice is created and a note asks you to review it.
The module works with the standard Magento checkout. It takes one-time payments on the ECPay page only. It has no refunds from Magento, 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 store cannot receive the notification, check the payment in the ECPay back-office. ECPay is not offered for orders created in the Admin.
Orders and refunds
Order statuses
Pending Payment: the order was placed and the customer was sent to ECPay, but ECPay has not confirmed the payment yet, or the customer chose ATM, CVS or Barcode and received the payment details. There is no invoice. A note shows when the payment details were received.
Processing: the payment was confirmed. The invoice is created with the ECPay TradeNo as the transaction ID, and a note shows the TradeNo and the amount in TWD (with a test mode mark for sandbox payments).
On Hold: ECPay reported a different amount or currency than the order (for example, the order total has cents and ECPay charged the rounded amount), or a sandbox payment arrived after you switched to live mode (no real money was collected). No invoice is created. The note shows the actual payment. Compare it with the ECPay back-office, then fulfil the order or refund the payment there.
Canceled: ECPay reported that the latest payment failed, the customer cancelled on the pending page, the payment could not be started, or the order was cancelled in Magento. A payment that arrives for an order that was already cancelled leaves the order cancelled, without an invoice, and adds a note for review; the stock is not taken again.
Closed: the order was fully refunded with a credit memo.
Repeated notifications are ignored. A paid or cancelled order is never reopened by a late failure. A second payment for a cart that is already paid, for example from two browser tabs, is recorded as a 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 an order paid, because ECPay collects no money for them. The notes are order comments that the customer does not see.
ECPay payment information
On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once ECPay has answered, MerchantTradeNo, ECPay TradeNo, ECPay payment type, ECPay method, ECPay received amount and ECPay mode, and the ATM, CVS or Barcode details. The customer sees the title and the payment details only. The Information tab also has the section ECPay payment attempts with every attempt of the cart: MerchantTradeNo, Mode, Method, Requested TWD, Status, ECPay TradeNo, Received TWD and Response code. It is shown for old orders too, also when the module is disabled.
Refunds
Refunds from Magento are not sent to ECPay. Refund the payment in the ECPay back-office, then create a credit memo for the invoice with Refund Offline to record the refund in Magento. A full refund closes the order (Closed).
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox ECPay Payment Gateway is the first row of the VibeFox ECPay Payment Gateway 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-ecpay 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, ECPay 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 by the ECPay notifications, and the customer's return still works.
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
ECPay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the customer's cart is in TWD and its total is at least 1 TWD, and, in live mode, that the MerchantID, HashKey and HashIV are set. Saving the settings shows a warning when the keys or the TWD currency are 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: the ECPay notification did not reach your store (site down, firewall, basic authentication, maintenance mode). ECPay retries several times. You can also check the trade in the ECPay back-office. Rejected notifications are written to the log in any case; the log is at the bottom of the group.
Notification answers 0|CheckMacValue verification failed: the HashKey or HashIV 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 cart was being processed by another request at the same moment, or the order could not be updated. ECPay sends the notification again. The reason is in the log.
The notification URL shows 0|POST required in the browser: this is normal. The URL accepts only requests from ECPay.
Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. ECPay sends the notification again later.
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 On Hold after payment: read the order notes and the ECPay payment attempts section (see Order statuses), compare with the ECPay back-office, then fulfil the order or refund the payment there.
An ATM, CVS or Barcode order was cancelled before the customer paid: the Magento cron cancelled it after the Pending Payment Order Lifetime. Set the lifetime longer than the ECPay payment deadline (see Checkout).
There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the ECPay back-office, then use 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.
Developers can change the parameters sent to ECPay with the Magento event ecpay_p_request_params; the merchant, trade number and amount cannot be changed by it.
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_EcpayPayment. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_EcpayPayment to remove the data, then bin/magento module:disable Vibefox_EcpayPayment, delete the folder app/code/Vibefox/EcpayPayment and run bin/magento setup:upgrade.
The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a 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 invoices, payment notes and transaction IDs.
ECPay is a trademark of its respective owner. This module is not affiliated with or endorsed by ECPay.