README

一款零第三方依赖的 PHP 支付聚合包，基于微信支付 V3 API 实现主要功能，并通过插件机制轻松扩展新接口与支付宝等新渠道。

要求 PHP >= 8.0，仅依赖 PHP 内置扩展（curl / json / openssl），不依赖任何第三方 Composer 包。

特性

✅ 基于微信支付 V3 API，支持 RSA-SHA256 请求签名、响应验签、回调 AES-256-GCM 解密
✅ 已内置主要接口：Native / JSAPI / APP / H5 下单、订单查询、关闭订单、申请退款、退款查询、回调验签解密
✅ 商家转账（新版）：发起 / 查询 / 撤销 / 免确认授权，支持按商户单号或微信转账单号查询
✅ 账单下载：申请交易账单 / 资金账单、下载账单文件（自动签名）
✅ 分账：请求 / 查询 / 完结 / 回退 / 接收方管理 / 剩余待分金额
✅ 一个接口一个插件：每个微信支付 API 对应一个独立插件，新增 / 覆盖接口无需改动框架
✅ 管道（Pipeline）串联插件：业务插件 → 签名 → 发送 → 验签 → 解析，链路清晰可扩展
✅ 预留支付宝等新渠道扩展：统一 DriverInterface 驱动契约 + Pay::extend() 渠道注册
✅ 零第三方依赖，接口风格统一，返回值均为数组，方便对接

环境要求

项目	要求
PHP	>= 8.0
扩展	ext-curl、ext-json、ext-openssl

安装

composer require mh-code/pay

（本地开发：克隆仓库后执行 composer install 即可生成自动加载文件。）

快速开始

<?php

use MHCode\Pay\Pay;

$wechat = Pay::wechat([
    'mch_id' => '1900000000',                 // 商户号
    'serial_no' => 'XXXXXX',                  // 商户API证书序列号
    'private_key_path' => '/path/apiclient_key.pem', // 商户API私钥(或 private_key 直接传 PEM 内容)
    'apiv3_key' => '0123456789abcdef0123456789abcdef', // APIv3密钥
    'wechatpay_public_key_path' => '/path/wechatpay_public_key.pem', // 验签推荐微信支付公钥(无过期时间)；或 platform_cert_path 用平台证书
    'app_id' => 'wx8888888888888888',         // 公众号/小程序/APP appid
    'notify_url' => 'https://example.com/notify.php',  // 默认回调地址
]);

// Native 扫码支付
$result = $wechat->native([
    'description' => '示例商品',
    'out_trade_no' => 'ORDER20260816120000',
    'amount' => 1, // 单位：分
]);

echo $result['code_url']; // 生成二维码给用户扫码

回调处理

$notify = $wechat->callback(getallheaders(), file_get_contents('php://input'));

// $notify['event_type'] 事件类型, $notify['data'] 解密后的业务数据
// 处理业务后应答：
echo WechatPay::success(); // {"code":"SUCCESS","message":"成功"}

支持的接口（场景）

场景	方法	微信支付接口
native	`native($params)`	下单 - Native（扫码）
jsapi	`jsapi($params)`	下单 - JSAPI / 小程序
app	`app($params)`	下单 - APP
h5	`h5($params)`	下单 - H5
query	`query($params)`	订单查询
close	`close($params)`	关闭订单
refund	`refund($params)`	申请退款
query_refund	`queryRefund($params)`	退款查询
transfer	`transfer($params)`	商家转账（新版，用户确认收款）
transfer_query	`queryTransfer($params)`	转账单查询（按商户单号）
transfer_cancel	`cancelTransfer($params)`	撤销转账
transfer_confirm	`confirmTransfer($params)`	转账免确认收款授权
transfer_query_no	`queryTransferByNo($params)`	转账单查询（按微信单号）
bill_trade	`billTrade($params)`	申请交易账单
bill_fundflow	`billFundflow($params)`	申请资金账单
bill_download	`billDownload($params)`	用 token 重新下载账单文件
profitsharing	`profitSharing($params)`	请求分账
profitsharing_query	`queryProfitSharing($params)`	查询分账结果
profitsharing_return	`profitSharingReturn($params)`	请求分账回退
profitsharing_return_query	`queryProfitSharingReturn($params)`	查询分账回退结果
profitsharing_finish	`finishProfitSharing($params)`	完结分账
profitsharing_receiver_add	`addProfitSharingReceiver($params)`	添加分账接收方
profitsharing_receiver_delete	`deleteProfitSharingReceiver($params)`	删除分账接收方
profitsharing_amounts	`queryProfitSharingAmounts($params)`	查询剩余待分金额
callback	`callback($headers, $body)`	回调验签解密

插件扩展（一个接口一个插件）

不常用的接口无需内置，编写一个实现 PluginInterface 的插件类即可接入（如分账已内置，示例以未内置的「商家券核销」演示）：

use MHCode\Pay\Contract\PluginInterface;
use MHCode\Pay\Support\Rocket;

class BusifavorUsePlugin implements PluginInterface
{
    public function handle(Rocket $rocket, \Closure $next): Rocket
    {
        $params = $rocket->getParams();

        $rocket->setMethod('POST');
        $rocket->setUrl('/v3/marketing/busifavor/coupons/use');
        $rocket->setPayload([
            'coupon_code' => $params['coupon_code'],
            'stock_id' => $params['stock_id'],
            'out_request_no' => $params['out_request_no'],
            'appid' => $rocket->getConfig('app_id'),
        ]);

        return $next($rocket); // 签名/发送/验签/解析自动复用
    }
}

$wechat->extend('busifavor_use', BusifavorUsePlugin::class);
$result = $wechat->scene('busifavor_use', ['coupon_code' => 'CARD-CODE-001', 'stock_id' => '98000001', 'out_request_no' => 'USE001']);

扩展新渠道（支付宝）

实现 DriverInterface 并在门面注册即可，调用方代码无需感知渠道差异：

use MHCode\Pay\Pay;

Pay::extend('alipay', AlipayPay::class); // 自定义驱动，复用同一套插件管道

$alipay = Pay::driver('alipay', $config);
$result = $alipay->scene('wap', $params);

异常处理

所有异常继承 MHCode\Pay\Exception\PayException：

异常	场景
`InvalidConfigException`	缺少/非法配置
`InvalidParamsException`	缺少/非法业务参数
`SignatureException`	签名失败、验签失败
`HttpException`	网络错误、超时
`PayException`	微信返回业务错误及其他错误

try {
    $result = $wechat->native($params);
} catch (\MHCode\Pay\Exception\PayException $e) {
    // 处理异常
}

目录结构

├── composer.json
├── src
│   ├── Pay.php                       # 门面（入口）
│   ├── Contract
│   │   ├── DriverInterface.php       # 渠道驱动契约
│   │   └── PluginInterface.php       # 插件契约
│   ├── Exception                     # 异常体系
│   ├── Support                       # 渠道无关通用组件
│   │   ├── Rocket.php                # 请求上下文
│   │   ├── Pipeline.php              # 插件管道
│   │   ├── Str.php                   # 字符串工具
│   │   ├── Http.php                  # cURL 客户端
│   │   └── Plugin                    # 通用链路插件（跨渠道复用）
│   │       ├── SendRequestPlugin.php # 发送请求
│   │       └── ParseResponsePlugin.php # 解析响应
│   └── Channel
│       └── Wechat
│           ├── WechatPay.php         # 微信支付驱动
│           ├── Plugin                # 业务插件（一个接口一个插件）
│           │   ├── NativePayPlugin.php
│           │   ├── JsapiPayPlugin.php
│           │   ├── AppPayPlugin.php
│           │   ├── H5PayPlugin.php
│           │   ├── QueryOrderPlugin.php
│           │   ├── CloseOrderPlugin.php
│           │   ├── RefundPlugin.php
│           │   ├── QueryRefundPlugin.php
│           │   ├── TransferPlugin.php
│           │   ├── QueryTransferPlugin.php
│           │   ├── CancelTransferPlugin.php
│           │   ├── ConfirmTransferPlugin.php
│           │   ├── QueryTransferByBillNoPlugin.php
│           │   ├── BillTradePlugin.php
│           │   ├── BillFundflowPlugin.php
│           │   ├── DownloadBillPlugin.php
│           │   ├── ProfitSharingPlugin.php
│           │   ├── QueryProfitSharingPlugin.php
│           │   ├── ProfitSharingReturnPlugin.php
│           │   ├── QueryProfitSharingReturnPlugin.php
│           │   ├── FinishProfitSharingPlugin.php
│           │   ├── AddProfitSharingReceiverPlugin.php
│           │   ├── DeleteProfitSharingReceiverPlugin.php
│           │   └── QueryProfitSharingAmountsPlugin.php
│           └── Support               # 渠道工具类与链路插件
│               ├── AbstractBusinessPlugin.php # 业务插件抽象基类
│               ├── Config.php        # 配置容器
│               ├── Signer.php        # 请求签名器
│               ├── Verifier.php      # 响应验签器
│               ├── AesUtil.php       # 回调解密器
│               ├── SignPlugin.php    # 渠道链路插件：请求签名
│               ├── VerifyResponsePlugin.php # 渠道链路插件：响应验签
│               └── CallbackPlugin.php # 回调处理（验签+解密）
├── examples                           # 代码示例
└── tests
    └── smoke.php                     # 冒烟测试（无需网络）

文档

安全说明

生产环境必须配置微信支付平台证书并保持 verify_response 开启，防止响应被篡改
商户私钥、APIv3 密钥等敏感信息严禁写入代码仓库，建议通过环境变量 / 配置中心注入
回调处理务必校验订单金额并做好幂等，防止重复入账

License

MIT

mh-code / pay

Package info

Security

Statistics