- How do I install tsaiyihua/laravel-ecpay in a Laravel app?
- Install it with Composer using composer require tsaiyihua/laravel-ecpay. Laravel's package discovery should register the service provider and the ECPay facade automatically, so manual edits to config/app.php are usually unnecessary. After that, publish the config file with php artisan vendor:publish and fill in your merchant credentials; check the README for the exact publish tag of this package.
- Which Laravel versions does laravel-ecpay support?
- The 3.4.0 release note states support for Laravel 13, and earlier 3.x releases cover prior framework majors. Because framework-major compatibility releases sometimes also raise the PHP floor or shift illuminate/* constraints, verify the package's composer.json requirements against your pinned Laravel and PHP versions before committing to an upgrade. If you are still on Laravel 11 or 12, the bump is routine dependency hygiene rather than a feature upgrade.
- How do I configure my ECPay MerchantID, HashKey and HashIV in Laravel?
- After publishing the config file you set your ECPay MerchantID, HashKey, HashIV, and the target environment (staging or production) there. Keep the real values in your .env file rather than in version control, since the hash key and IV are what protect every request signature. The README lists the exact config keys and environment names this package expects.
- Does this package generate and verify the CheckMacValue checksum automatically?
- Yes. The package handles request formatting and CheckMacValue generation for outgoing API calls, and it verifies the checksum on ECPay's server-to-server callbacks. You should still validate the merchant trade number, amount, and RtnCode against your own order record before treating a payment as complete. Never trust a callback whose signature you have not verified and whose order you cannot match locally.
- Which ECPay payment methods can I use with this package?
- The package supports the common ECPay payment methods, typically credit card, ATM virtual account, CVS code, and barcode, selected through the payment request parameters. Which methods are actually available depends on what your ECPay merchant account has been approved for, so confirm the list against both the package docs and your ECPay contract. Each method has its own required fields and different callback timing.
- How do I handle ECPay payment callbacks and ReturnURL in Laravel?
- ECPay posts form-encoded results to the ReturnURL you configure for server-to-server notification and, optionally, redirects the customer's browser to your OrderResultURL or ClientBackURL. Register these as POST routes excluded from CSRF verification, verify the CheckMacValue, then reply with the expected 1|OK acknowledgement so ECPay stops retrying. Do not return a success response before your order has actually been updated.
- Can I create logistics (物流) orders and e-invoices (電子發票) with this package, not just payments?
- Yes. Beyond payments, the package covers ECPay logistics and e-invoice workflows, exposing them as separate services through the facade. Logistics and invoice APIs have their own parameter sets and callback formats, so treat them as distinct integrations even though they share the same merchant credentials and checksum logic. Compare the package's coverage against the specific logistics subtype (CVS pickup, home delivery) and invoice type you need.
- How do I test my ECPay integration without taking real payments?
- ECPay provides a staging environment with its own merchant credentials and API endpoints; point the package's environment setting at staging and use those test credentials instead of your production ones. Staging behaves like production for signatures and callbacks but does not move real money, which makes it suitable for end-to-end tests. Never put production keys in test fixtures or CI secrets that developers can read.
- Is tsaiyihua/laravel-ecpay an official ECPay package, and what are the alternatives?
- No. It is an unofficial, community-maintained package and is not affiliated with or endorsed by ECPay (綠界科技). The alternatives are integrating ECPay's official API documentation and SDKs yourself, or choosing another community package. The value this one offers is a Laravel-shaped config, facade, and checksum handling instead of a raw HTTP client.
- Is laravel-ecpay safe for production, and how actively is it maintained?
- Assess it like any small community dependency: check release cadence, whether CI actually runs against the Laravel versions it claims, open issues filed after major framework releases, and the maintainer's bus factor. Pin an exact version in composer.json and wrap facade calls in your own service or action classes so a future swap does not ripple through the codebase. For payment flows specifically, add your own idempotency and reconciliation logic rather than relying on the package alone.