# pay

**Repository Path**: mh-code/pay

## Basic Information

- **Project Name**: pay
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mh-code/pay

一款**零第三方依赖**的 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 |

## 安装

```bash
composer require mh-code/pay
```

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

## 快速开始

```php
<?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']; // 生成二维码给用户扫码
```

### 回调处理

```php
$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` 的插件类即可接入（如分账已内置，示例以未内置的「商家券核销」演示）：

```php
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` 并在门面注册即可，调用方代码无需感知渠道差异：

```php
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` | 微信返回业务错误及其他错误 |

```php
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                     # 冒烟测试（无需网络）
```

## 文档

- [AI 开发约定与工作流](AGENTS.md)（参与持续开发前必读）
- [安装与配置](docs/01-安装与配置.md)
- [微信支付 V3 接口详解](docs/02-微信支付V3.md)
- [回调通知处理](docs/03-回调通知.md)
- [插件扩展指南](docs/04-插件扩展.md)
- [新渠道接入指南（支付宝）](docs/05-新渠道接入.md)
- [AI 工作流（持续开发指南）](docs/06-AI工作流.md)

## 安全说明

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

## License

[MIT](LICENSE)