sungmee/laravel-payment

『LaraPay』是为 Laravel 量身定制的 第三方支付 扩展包，可根据第三方支付平台提供的 API 接口，无限扩展本包支持的平台。

0.1.0 2018-02-05 18:28 UTC

Requires

• php: >=7.0.0
• illuminate/support: >=4.0
• ixudra/curl: 6.*

MIT

• SUNGMEE

• payment
• laravel
• packages

README

『LaraPay』是为 Laravel 量身定制的第三方支付扩展包，支持根据第三方支付平台提供的 API 接口无限扩展。特别适合对接国内各类三方/四方支付平台。

版本要求

软件	版本
PHP	^8.3
Laravel	^13.0
illuminate/support	^13.0
illuminate/contracts	^13.0

安装

composer require sungmee/laravel-payment

发布配置文件和迁移：

php artisan vendor:publish --provider="Sungmee\LaraPay\ServiceProvider"
php artisan migrate

配置文件 config/pay.php 发布后，可在 .env 中设置：

# 默认支付平台
PAY_GATEWAY=Example

# 用户模型
PAY_USER_MODEL=App\Models\User

# 异步通知地址（由支付平台回调）
PAY_NOTIFY_URL=https://your-domain.com/payment/notify/offline

# 同步跳转地址（支付成功后用户跳转回站）
PAY_RETURN_URL=https://your-domain.com/payment/notify/page

# 支付成功后重定向地址
PAY_REDIRECT_TO=https://your-domain.com

# 手续费百分比
PAY_FEE=0.01

# 汇率差值
PAY_ER_DIFF=0.07

快速开始

支付

use Sungmee\LaraPay\Facade as Pay;

// 支付参数
$params = [
    'amount'       => 100,          // 金额，单位：分
    'product_name' => '商品名称',
    'bank_code'    => 'ICBC',       // 银行代码（银联支付时使用）
    'service_type' => 'direct_pay', // 支付服务类型
];

// 银联支付 — 返回 POST 表单数组，用于前端组装跳转到支付页面
$result = Pay::bankPay($params);

// 联合支付 — 返回 POST 表单数组
$result = Pay::unionPay($params);

// 扫码支付 — 返回二维码链接或二维码数据字符串
$result = Pay::scanPay($params);

// [$payment, $payData] = Pay::scanPay($params);
// $payment → \Sungmee\LaraPay\Payment 实例
// $payData → 支付平台返回的原始数据（含 qrcode 等）

订单查询

use Sungmee\LaraPay\Facade as Pay;

$orderNo = 1; // 支付单号，即 payments 表 ID
[$payment, $queryResult] = Pay::query($orderNo);
// $payment     → \Sungmee\LaraPay\Payment 实例
// $queryResult → 支付平台返回的订单明细

支付结果通知

路由已自动注册：

路径	方法	说明
/payment/notify/offline	POST/GET	支付平台异步通知
/payment/notify/page	POST/GET	支付成功后页面跳转通知

订单验签成功且状态变为 CAPTURE（已付款）时，触发事件：

\Sungmee\LaraPay\Events\Capture

事件携带 $payment 属性（\Sungmee\LaraPay\Payment 实例），可在事件监听器中处理业务逻辑：

// App\Providers\EventServiceProvider.php
protected $listen = [
    \Sungmee\LaraPay\Events\Capture::class => [
        \App\Listeners\HandlePaymentCapture::class,
    ],
];

运行中指定支付平台

use Sungmee\LaraPay\Pay;

$pay = new Pay;
$gateway = $pay->Example();

$gateway->bankPay($params);
$gateway->unionPay($params);
$gateway->scanPay($params);

扩展支付平台

遵循 PSR-4 规则，创建新的网关类，继承 Base 并实现 GatewayInterface：

src/Gateways/
└── YourGateway/
    └── YourGateway.php

<?php

namespace Sungmee\LaraPay\Gateways\YourGateway;

use Sungmee\LaraPay\Base;
use Sungmee\LaraPay\GatewayInterface;

class YourGateway extends Base implements GatewayInterface
{
    protected $paymentNo = 'no';

    public function __construct()
    {
        parent::__construct();
        // 读取当前网关配置：$this->config['gateways']['YourGateway']
    }

    public function bankPayAlias($params) { /* ... */ }
    public function unionPayAlias($params) { /* ... */ }
    public function scanPayAlias($params) { /* ... */ }
    public function offlineNotifyAlias($payment, $request) { /* ... */ }
    public function pageNotifyAlias($payment, $request) { /* ... */ }
    public function queryAlias($payment) { /* ... */ }
}

在 config/pay.php 的 gateways 中添加对应配置，并将 .env 的 PAY_GATEWAY 设为新平台名称。

数据库 payments 表结构：

字段	类型	说明
id	int (PK)	支付单号
user_id	int	用户 ID
gateway	string(28)	支付平台标识
type	string(28)	支付类型
amount	int	金额（分）
status	enum	PENDING/VOID/REFUNDED/CAPTURE/SUCCESS/FAIL
metas	json	支付平台原始返回数据
created_at	timestamp	创建时间
updated_at	timestamp	更新时间
deleted_at	timestamp	软删除时间

支付状态说明

状态	说明
PENDING	待处理
VOID	无效（付款前取消）
REFUNDED	已退款（付款后退款）
CAPTURE	已付款
SUCCESS	支付流程已完成
FAIL	支付失败

内置支付平台

• Example — 示例网关，作为开发模版
• CvPay — CV 支付系统
• DinPay — 多得宝支付
• WbPay — 万币聚合支付
• QdPay — 591 支付系统

许可证

MIT