omnipay-taiwan / omnipay-ecpay

v1.1.10 2026-09-05 13:10 UTC

Requires

• ecpay/sdk: ^1.3
• omnipay/common: ^3.0

Requires (Dev)

• nyholm/psr7: ^1.3
• omnipay/tests: ^3.0|^4.0
• squizlabs/php_codesniffer: ^3

MIT

• recca0120

• omnipay
• ecpay

Published on Packagist.org on 2026-09-05 13:11 UTC

README

ECPay (綠界科技) gateway for the Omnipay PHP payment processing library

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP 5.3+. This package implements ECPay (綠界科技) support for Omnipay.

ECPay's own SDK (ecpay/sdk) is used under the hood for request signing, checksum verification and URL encoding, wrapped to expose Omnipay's standard Gateway / RequestInterface / ResponseInterface contracts. Supported payment methods (via ChoosePayment) are credit card (including installments, recurring/period payments and card binding), ATM, convenience store code / barcode, and BNPL (無卡分期, consumer credit installment without a card). Electronic invoice fields are also supported when invoicing is enabled.

Install

Install the gateway using require. Require the league/omnipay base package and this gateway.

$ composer require league/omnipay omnipay-taiwan/omnipay-ecpay

Usage

The following gateways are provided by this package:

• ecpay

For general usage instructions, please see the main Omnipay repository.

Purchase

$gateway = Omnipay::create('ECPay');
$gateway->initialize([
    'MerchantID' => 'your-merchant-id',
    'HashKey' => 'your-hash-key',
    'HashIV' => 'your-hash-iv',
    'testMode' => true,
]);

$response = $gateway->purchase([
    'transactionId' => 'order-number',
    'amount' => '1000',
    'currency' => 'TWD',
    'description' => 'order description',
    'returnUrl' => 'https://example.com/return',
    'notifyUrl' => 'https://example.com/notify',
    'ChoosePayment' => 'Credit', // or ATM, CVS, BARCODE, BNPL, ALL
])->send();

if ($response->isRedirect()) {
    $response->redirect();
}

Complete purchase / accept notification

ECPay sends a server-to-server notification once payment completes. Its CheckMacValue signature is verified before the notification is trusted, and an InvalidRequestException is thrown if the signature does not match:

$response = $gateway->acceptNotification()->send();

if ($response->isSuccessful()) {
    // mark order as paid
}

echo $response->getReply(); // '1|OK', required by ECPay

Refund and void

$gateway->refund([
    'transactionId' => 'order-number',
    'transactionReference' => 'ecpay-trade-no',
    'amount' => '1000',
])->send();

$gateway->void([
    'transactionId' => 'order-number',
    'transactionReference' => 'ecpay-trade-no',
    'amount' => '1000',
])->send();

Fetch transaction

$gateway->fetchTransaction([
    'transactionId' => 'order-number',
])->send();

Support

If you are having general issues with Omnipay, we suggest posting on Stack Overflow. Be sure to add the omnipay tag so it can be easily found.

If you want to keep up to date with release announcements, discuss ideas for the project, or ask more detailed questions, there is also a mailing list which you can subscribe to.

If you believe you have found a bug, please report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• recca0120
• All Contributors

License

The MIT License (MIT). Please see License File for more information.