README

Laravel ECPay

Laravel ECPay 是连接绿界的非官方套件

系统需求

• v3.x
  • PHP >= 8.0
  • Laravel >= 9.0
• v2.x
  • PHP >= 7.2 且 < 8.0
  • Laravel < 9 且 >= 6.0
• v1.x (不维护更新)
  • PHP >= 7 且 < 8.0
  • Laravel < 6.0 且 >= 5.7

安装

composer require tsaiyihua/laravel-ecpay

环境设置

php artisan vendor:publish --tag=ecpay

这里会将配置文件ecpay.php复制一份到config目录下。

.env文件中加入

ECPAY_MERCHANT_ID=
ECPAY_HASH_KEY=
ECPAY_HASH_IV=
ECPAY_INVOICE_HASH_KEY=
ECPAY_INVOICE_HASH_IV=

• 金流测试用的参数值请参考介接文件 ecpay_gw_p110.pdf 第11页。
• 查询发票用的参数请参考介接文件 ecpay_004.pdf 第6页。

用法

基本用法

• 产品资料单笔时可简单只传递 ItemName 及 TotalAmount

use TsaiYiHua\ECPay\Checkout;

class CheckoutController extends Controller
{
    protected $checkout;
    
    public function __construct(Checkout $checkout)
    {
        $this->checkout = $checkout;
    }

    public function sendOrder()
    {
        $formData = [
            'UserId' => 1, // 用戶ID , Optional
            'ItemDescription' => '產品簡介',
            'ItemName' => 'Product Name',
            'TotalAmount' => '2000',
            'PaymentMethod' => 'Credit', // ALL, Credit, ATM, WebATM
        ];
        return $this->checkout->setPostData($formData)->send();
    }

需要分期付款时

• 加上 withInstallment(分期期数)
• 信用卡分期可用参数为:3,6,12,18,24
• 示例： 3,6 示例
  承上，在 return 时，加上 withInstallment 即可

    return $this->checkout->setPostData($formData)->withInstallment('3,6')->send();

定期定额扣款

• 加上 withPeriodAmount($periodAmt)

示例

承上，加上參數，帶入 withPeriodAmount 即可

...
    $periodAmt = [
        'PeriodAmount' => 2550,
        'PeriodType' => 'M',
        'Frequency' => '1',
        'ExecTimes' => 10,
        'PeriodReturnURL'
    ];
    return $this->checkout->setPostData($formData)->withPeriodAmount($periodAmt)->send();

需要开立发票时

• 加上 withInvoice($invData) 即可。
• 开立发票时，产品内容必须符合既定格式发送，不能只带 ItemName 及 TotalAmount
• 开立发票时，特店必须要有会员系统并传送会员相关资料
• 测试开立发票时，MerchantID 请设 2000132

示例

use TsaiYiHua\ECPay\Checkout;

class CheckoutController extends Controller
{
    protected $checkout;
    
    public function __construct(Checkout $checkout)
    {
        $this->checkout = $checkout;
    }

    public function sendOrder()
    {
        $items[0] = [
            'name' => '產品333',
            'qty' => '3',
            'unit' => '個',
            'price' => '150'
        ];
        $formData = [
            'itemDescription' => '產品簡介',
            'items' => $items,
            'paymentMethod' => 'Credit',
            'userId' => 1
        ];
        $invData = [
            'Items' => $items,
            'UserId' => 1,
            'CustomerName' => 'User Name',
            'CustomerAddr' => 'ABC 123',
            'CustomerEmail' => 'email@address'
        ];
        return $this->checkout->setPostData($formData)->withInvoice($invData)->send();
    }

查询订单

use TsaiYiHua\ECPay\QueryTradeInfo;

class QueryTradeController extends Controller
{
    protected $queryTradeInfo;
    
    public function __construct(QueryTradeInfo $queryTradeInfo)
    {
        $this->queryTradeInfo = $queryTradeInfo;
    }
    
    public function queryInfo($orderId)
    {
        return $this->queryTradeInfo->getData($orderId)->query();
    }
}

查询发票

use TsaiYiHua\ECPay\QueryInvoice;

class QueryInvoiceController extends Controller
{
    protected $queryInvoice;

    public function __construct(QueryInvoice $queryInvoice)
    {
        $this->queryInvoice = $queryInvoice;
    }

    public function queryInvInfo($orderId)
    {
        return $this->queryInvoice->getData($orderId)->query();
    }
}

开立发票

use TsaiYiHua\ECPay\Invoice;
use TsaiYiHua\ECPay\Constants\ECPayDonation;
use TsaiYiHua\ECPay\Services\StringService;

class InvoiceController extends Controller
{
    public function __construct(Invoice $invoice)
    {
        $this->invoice = $invoice;
    }

    public function issueInvoice()
    {
        $itemData[] = [
            'name' => 'product name',
            'qty' => 1,
            'unit' => 'piece',
            'price' => 5000
        ];
        $invData = [
            'UserId' => 1,
            'Items' => $itemData,
            'CustomerName' => 'User Name',
            'CustomerEmail' => 'email@address.com',
            'CustomerPhone' => '0912345678',
            'OrderId' => StringService::identifyNumberGenerator('O'),
            'Donation' => ECPayDonation::Yes,
            'LoveCode' => 168001,
            'Print' => 0,
            'CarruerType' => 1
        ];
        return $this->invoice->setPostData($invData)->send();
    }
}

套件中有设置和绿界沟通通用的route及基本处理方法，如果要有自己的处理逻辑要用自己写好的route，担心和套件原设定的route冲突时

• 在 app/Http/Providers/AppServiceProvider 的 register 加入

ECPay::ignoreRoutes();

如果要用自己发送数据的页面

• 方法一： 在 .env 裡使用 ECPAY_SEND_FORM 的环境变量来指定。
• 方法二： 直接指定 ECPay::$sendForm 的值来指定。

所有文件列的参数基本上都可用，参数用法请参考绿界串接文件

• 返回参数的背景通知(ReturnURL)，套件里有预定义的网址，但只限于通知，如果要有写入数据库的设计，要再设计自己的返回通知网址。
• OrderResultURL 为结账完返回自己的站台的网址，不能与 ReturnURL 相同。

参考文件

• 绿界科技全方位金流信用卡介接技术文件 (2021-08-19)
  • V 5.2.8
  • 文件编号 gw_p110
  • 文件位置 documents/ecpay_gw_p110.pdf
• 绿界科技B2C电子发票介接技术文件 (2022-01-03)
  • V 3.6.4
  • 文件编号 gw_i100
  • 文件位置 documents/ecpay_004.pdf
• 绿界科技全方位金流介接技术文件 (2021-11-30)
  • V 5.3.11
  • 文件编号 gw_p100
  • 文件位置 documents/ecpay_011.pdf