README

这是一个内部收单系统，依赖 yansongda/pay 这个组件，本收单系统统一了调用方式。

备注：交易金额单位是分；2.x 和 3.x 版本对外接口一致，只是内部调用的第三方接口版本不同，本扩展拉齐了开发体验。

环境需求

PHP ^8.2
Laravel ^12.0 | ^13.0
ext-json, ext-openssl, ext-bcmath

安装

composer require "larva/laravel-pay"

配置

发布配置文件和迁移文件：

php artisan vendor:publish --provider="Larva\Pay\PayServiceProvider"

发布后可在 config/pay.php 中配置支付宝、微信、银联的商户参数。配置项说明请参考 yansongda/pay 文档。

支持的支付渠道

渠道	常量	支付类型
微信	`Pay::CHANNEL_WECHAT`	web、wap、app、pos、scan、mini
支付宝	`Pay::CHANNEL_ALIPAY`	web、wap、app、scan
银联	`Pay::CHANNEL_UNIONPAY`	-

路由注册

在 AppServiceProvider 的 boot 方法中注册路由：

\Larva\Pay\Pay::routes();

在中间件 App\Http\Middleware\VerifyCsrfToken 中排除支付回调路由：

protected $except = [
    'pay',
];

使用方法

创建收款单

use Larva\Pay\Models\Charge;

$charge = Charge::create([
    'trade_channel' => 'wechat',      // 支付渠道
    'trade_type'    => 'scan',        // 支付类型
    'subject'       => '订单标题',
    'description'   => '商品描述',
    'total_amount'  => 100,           // 金额，单位：分
    'client_ip'     => $request->ip(),
    'metadata'      => ['openid' => 'xxx'], // 微信小程序支付需要 openid
]);

创建收款单后会自动预下单并写入 credential（支付凭证），前端可据此调起支付。

如果创建时不指定渠道和类型，后续也可动态获取凭证：

$credential = $charge->getCredential('alipay', 'web');

查询收款单

$charge = \Larva\Pay\Pay::getCharge($id);

发起退款

$refund = $charge->refund('退款原因');

退款单创建后会自动通过队列提交到支付网关。

企业付款（提现）

use Larva\Pay\Models\Transfer;

$transfer = Transfer::create([
    'trade_channel' => 'alipay',
    'amount'        => 100,           // 金额，单位：分
    'description'   => '提现备注',
    'recipient'     => [
        'account'      => 'user@example.com',
        'account_type' => 'ALIPAY_LOGON_ID',
        'name'         => '张三',
    ],
]);

付款单创建后会自动通过队列提交到支付网关。

事件

事件	描述
`\Larva\Pay\Events\ChargeSucceeded`	收款成功
`\Larva\Pay\Events\ChargeFailed`	收款失败
`\Larva\Pay\Events\ChargeClosed`	收款已关闭
`\Larva\Pay\Events\RefundSucceeded`	退款成功
`\Larva\Pay\Events\RefundFailed`	退款失败
`\Larva\Pay\Events\RefundClosed`	退款关闭
`\Larva\Pay\Events\TransferSucceeded`	企业付款成功
`\Larva\Pay\Events\TransferFailed`	企业付款失败

所有事件类都使用 SerializesModels trait，可直接在队列监听器中使用。

订单关联

通过多态关联将你的订单模型与收款单绑定：

use Larva\Pay\Models\Charge;

class Order extends Model
{
    /**
     * 关联付款模型
     * @return \Illuminate\Database\Eloquent\Relations\MorphOne
     */
    public function charge()
    {
        return $this->morphOne(Charge::class, 'order');
    }

    /**
     * 发起退款
     * @param string $reason 退款描述
     * @return Model|Refund
     * @throws Exception
     */
    public function refund(string $reason)
    {
        if ($this->charge->paid && $this->charge->refundableAmount > 0) {
            $refund = $this->charge->refund($reason);
            $this->update(['refunded' => true]);
            return $refund;
        }
        throw new Exception('Not paid, no refund.');
    }
}

创建收款单时关联订单：

$order->charge()->create([
    'trade_channel' => 'wechat',
    'trade_type'    => 'scan',
    'subject'       => $order->title,
    'total_amount'  => $order->amount,
    'client_ip'     => $request->ip(),
]);

数据表结构

安装后会自动创建以下数据表：

pay_charges — 收款记录表
pay_refunds — 退款记录表
pay_transfer — 付款记录表

License

MIT

larva / laravel-pay

Maintainers

Package info

Statistics

Security