tansilu / hfpay-lib
Requires
- php: >=8.0
- ext-json: *
- guzzlehttp/guzzle: ^7.10
- php-di/php-di: ^7.1
Requires (Dev)
- phpunit/phpunit: ^9.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
PHP SDK,封装汇付天下数字藏品(NFT)支付相关接口:开户、钱包、绑卡、查询、下单、分账、退款、取现、一级市场开户等。
- 使用 PHP-DI 容器装配工厂,业务代码只面向
HFPayClient单例 - 支持两种签名方式:CFCA 远程签名服务器(默认,兼容老项目)与 RSA2 本地私钥加签
- 两种签名方式对业务代码完全透明:只改配置,不改调用
详细文档见 docs/README.md。
环境要求
| PHP 版本 | 依赖组合 | 状态 |
|---|---|---|
| 7.4 | guzzlehttp/guzzle ^7.10 + php-di/php-di ^6.4 | 已实测(PHP 7.4.3) |
| 8.0+ | guzzlehttp/guzzle ^7.10 + php-di/php-di ^7.x | 已实测(PHP 8.2.9) |
php-di目前线上最高版本为7.0.x,不存在 7.1。声明依赖时请写^7.0, 写成^7.1会导致composer require/composer install直接解析失败。
扩展要求:openssl(RSA 模式必需)、json、curl。
安装
composer require tansilu/hfpay-lib
快速开始
方式一:CFCA 远程签名(原有方式,默认)
<?php
require __DIR__ . '/vendor/autoload.php';
use Tansilu\HfPayLib\HFPayClient;
$config = [
'debug' => true, // true=测试环境,false=生产
'version' => '10',
'mid' => '6666000100064457', // 商户号
'sign_server' => 'https://sign.location.server/', // 本地签名服务器
'sign_file' => '/CFCA/HF123.pfx', // 签名服务器上的 pfx 路径
'sign_pwd' => '123456',
'cert_file' => '/CFCA/cert/CFCA_1234.cer', // 签名服务器上的证书路径
];
$client = HFPayClient::getInstance()->init($config);
// 查询钱包状态
$status = $client->query()->wallet('用户客户号');
var_dump($status->resp_code);
方式二:RSA2 本地私钥(推荐,无需签名服务器)
已接入 CFCA 的项目只改配置就能切过来,业务代码与回调代码都一行不用改。
原因是 SDK 支持复用历史配置键:
| 历史键(CFCA 用) | RSA 模式下的含义 |
|---|---|
sign_server | 填 rsa2(或 rsa)即表示启用本地 RSA,不再访问签名服务器 |
sign_file | 商户私钥路径(可写路径 / PEM / 裸 Base64) |
sign_pwd | 商户私钥密码,无密码留空 |
cert_file | 汇付公钥(路径 / PEM / 裸 Base64) |
于是下游项目的 .env 只改值、不改键名:
# 原 CFCA 配置
# hf_sign_server=https://sign.location.server/
# hf_sign_file=/CFCA/HF123.pfx
# hf_sign_pwd=123456
# hf_cert_file=/CFCA/cert/CFCA_1234.cer
# 切到 RSA
hf_sign_server=rsa2
hf_sign_file=/data/cert/merchant_private_key.pem
hf_sign_pwd=
hf_cert_file=/data/cert/hf_public_key.pem
代码侧(init() 与 new SignerHttpClient(...))完全保持原样即可。
新项目也可以直接用语义更清晰的配置键:
<?php
require __DIR__ . '/vendor/autoload.php';
use Tansilu\HfPayLib\HFPayClient;
$config = [
'debug' => true,
'version' => '10',
'mid' => '6666000100064457',
'sign_type' => 'rsa2', // 等价于 sign_server=rsa2
'mer_private_key' => __DIR__ . '/cert/merchant_private_key.pem', // 支持路径/Base64/PEM
'mer_private_key_pwd' => '', // 私钥密码,无密码留空
'hf_public_key' => __DIR__ . '/cert/hf_public_key.pem', // 汇付公钥
'callback' => 'https://your.domain/hfpay/notify', // 可选:自动填充 bg_ret_url
];
$client = HFPayClient::getInstance()->init($config);
$status = $client->query()->wallet('用户客户号'); // 与 CFCA 完全一致的调用方式
两种写法等价,
mer_private_key/hf_public_key优先,旧键仅作回退,原有 CFCA 配置不受影响。
签名方式对比
| 项目 | cfca(默认) | rsa2 / rsa |
|---|---|---|
| 加签位置 | 远程签名服务器(makeSign / verifySign) | 本地商户私钥,SHA256WithRSA |
| 网络依赖 | 需要能访问签名服务器 | 无 |
| 必填配置 | sign_server、sign_file、sign_pwd、cert_file | mer_private_key、hf_public_key(可用 sign_file/cert_file 旧键) |
| 请求报文 | 表单参数 + check_value | version、sign_type、mer_cust_id、data、sign |
| 响应处理 | check_value 走签名服务器验签解密 | data + sign 本地验签、敏感字段私钥解密 |
| 异步回调参数 | $_POST['check_value'] | $_POST['data'] + $_POST['sign'] |
| 敏感字段加密 | 由签名服务器处理 | SDK 自动用汇付公钥加密,响应自动解密 |
| 下游代码改动 | — | 无需改动:init() / SignerHttpClient / decode() 调用方式全部保持 |
sign_type 不区分大小写,rsa 等同于 rsa2;不填则默认 cfca。
sign_server 填 rsa/rsa2 时等价于 sign_type=rsa2,便于只改环境变量完成切换。
配置项
公共
| 配置 | 说明 |
|---|---|
debug | true 走测试环境 hfpay.testpnr.com,false 走生产 hfpay.cloudpnr.com |
version | 接口版本号,默认 10 |
mid | 商户号,会作为 mer_cust_id 自动注入每个请求 |
callback | 可选,异步通知地址,请求未显式传 bg_ret_url 时自动填充 |
CFCA 专有
| 配置 | 说明 |
|---|---|
sign_server | 本地签名服务器地址,缺失会抛 InitException |
sign_file | 签名服务器上的 pfx 文件路径(不是本地路径) |
sign_pwd | pfx 密码 |
cert_file | 签名服务器上的 cer 证书路径 |
RSA2 专有
| 配置 | 说明 |
|---|---|
sign_type | rsa2 或 rsa |
mer_private_key | 商户私钥,支持裸 Base64(PKCS#8)、PEM 全文、文件路径(别名 rsa_private_key) |
mer_private_key_pwd | 私钥密码,无密码可省略(别名 rsa_private_key_pwd) |
hf_public_key | 汇付公钥,支持裸 Base64(X.509)、PEM 全文、文件路径(别名 hf_rsa_public_key) |
RSA2 使用详解
1. 秘钥准备
| 秘钥 | 格式 | 说明 |
|---|---|---|
| 商户私钥 | PKCS#8(也兼容 PKCS#1) | 用于请求加签、响应/回调解密 |
| 汇付公钥 | X.509 | 用于响应/回调验签、敏感字段加密 |
三种写法都支持,推荐用文件路径(避免私钥进代码库):
'mer_private_key' => '/data/cert/merchant_private_key.pem', // 文件路径
'mer_private_key' => 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...', // 裸 Base64(无 PEM 头尾)
'mer_private_key' => "-----BEGIN PRIVATE KEY-----\n...", // PEM 全文
从 pfx 导出(可选):
# 商户私钥(PKCS#8,无密码)
openssl pkcs12 -in merchant.pfx -nocerts -nodes -out merchant_private_key.pem
# 商户证书(如需上传/核对)
openssl pkcs12 -in merchant.pfx -clcerts -nokeys -out merchant_cert.pem
# 汇付公钥转 PEM(原始为 Base64 时)
openssl rsa -pubin -in hf_public_key.pem -noout
2. 初始化
use Tansilu\HfPayLib\HFPayClient;
$client = HFPayClient::getInstance()->init([
'debug' => false,
'version' => '10',
'mid' => '6666000100064457',
'sign_type' => 'rsa2',
'mer_private_key' => '/data/cert/merchant_private_key.pem',
'hf_public_key' => '/data/cert/hf_public_key.pem',
'callback' => 'https://your.domain/hfpay/notify',
]);
配置有问题会在初始化时立刻抛 InitException(缺私钥、缺公钥、缺签名服务器、sign_type 不支持)。
3. 统一下单(RSA)
use Tansilu\HfPayLib\Constant;
use Tansilu\HfPayLib\factory\object\trade\DeviceInfo;
use Tansilu\HfPayLib\factory\object\trade\ObjectInfo;
use Tansilu\HfPayLib\factory\object\trade\UnifiedOrderRequest;
$objectInfo = ObjectInfo::make(Constant::MARKET_SUB); // 1=一级市场 2=二级市场
$objectInfo->objectType = 'DIGI';
$objectInfo->objectName = '创世藏品#001';
$objectInfo->objectAddr = '0x1234567890abcdef';
$objectInfo->chainBelong = 'ETH';
$objectInfo->chainId = '1001';
$objectInfo->objectStandard = 'ERC721';
$device = DeviceInfo::make(
(string)Constant::DEVICE_TYPE_MOBILE, // 设备类型
'127.0.0.1', // IP
'00:11:22:33:44:55' // MAC(或改用 IMEI)
);
$req = new UnifiedOrderRequest();
$req->order_date = date('Ymd');
$req->order_id = 'T' . date('YmdHis') . mt_rand(1000, 9999);
$req->user_cust_id = '6666000100064457';
$req->trans_amt = '0.01'; // 单位元,字符串两位小数
$req->goods_desc = '创世藏品#001';
$req->object_info = $objectInfo;
$req->dev_info_json = $device;
$order = $client->trade()->unifiedOrder($req);
if ($order !== null) {
echo $order->pay_url; // 跳转收银台地址
}
RSA 模式下 SDK 自动完成:user_mobile、id_card 等敏感字段用汇付公钥加密 → 参数按 key 升序排序并加签 → 组装外层报文 → 响应验签 → 敏感字段用商户私钥解密。
4. 查询
// 钱包状态
$wallet = $client->query()->wallet('用户客户号');
echo $wallet->resp_code;
// 余额(accountId 为空时必须指定 is_query_guarantee)
$balance = $client->query()->balance('用户客户号', '账户号');
// 交易状态
$trans = $client->query()->trans('订单号', '20261105', Constant::TRANS_TYPE_WALLET);
// 开户状态、绑卡信息、流水、链上余额
$client->query()->openStatus($orderId, $orderDate, Constant::TRANS_TYPE_WALLET);
$client->query()->bindCard('用户客户号');
$client->query()->record('用户客户号', '账户号', '20261101', '20261105', 20, 1);
$client->query()->chainBalance('用户客户号');
5. 文件上传(multipart)
RSA 模式下,文本参数参与加密与签名,文件流只走 multipart、不参与签名:
use Tansilu\HfPayLib\Constant;
use Tansilu\HfPayLib\factory\object\onelevel\UploadRequest;
$upload = new UploadRequest();
$upload->attach_no = '1';
$upload->trans_type = (string)Constant::ONE_UP_TRANS_TYPE_PERSONAL; // 7=个人开户
$upload->attach_type = (string)Constant::ONE_UP_ATTACH_TYPE_21; // 21=身份证正面
$upload->attach_desc = '身份证正面';
$upload->handle_type = (string)Constant::ONE_UP_HANDEL_TYPE_ADD;
$upload->attach_file = fopen('/data/idcard.jpg', 'rb');
$resp = $client->one()->upload($upload);
6. 异步回调处理
decode($raw) 是统一入口,CFCA 与 RSA 都支持,调用方式不变。
已接入 CFCA 的项目,回调处理代码一行都不用改:
// 历史写法保持可用:签名方式由配置决定,代码不用感知
$signer = new \Tansilu\HfPayLib\library\impl\SignerHttpClient(
$config['sign_server'],
$config['sign_file'],
$config['sign_pwd'],
$config['cert_file']
);
try {
// $raw 为回调原始报文:
// CFCA:check_value 字符串(走签名服务器验签解密)
// RSA :{"data":"...","sign":"..."} 的 JSON 串,或 data=..&sign=.. 的 query 串
$data = $signer->decode($raw);
} catch (\Tansilu\HfPayLib\exception\SignException $e) {
// 验签失败:直接丢弃,不要更新业务状态
exit('fail');
}
// 处理业务(判断 resp_code,幂等更新订单)
if (($data['resp_code'] ?? '') === 'C00000') {
// ...
}
echo 'success';
如果手上已经是 $_POST 数组,用 decodeCallback() 更直接(同样两种模式通用):
$data = $client->signer()->decodeCallback($_POST);
RSA 回调的 $raw 常见来源(存库时把整包存下来即可):
$post = $this->request->post();
$raw = $_SERVER['CONTENT_TYPE'] === 'application/json'
? file_get_contents('php://input')
: json_encode($post, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
RSA 模式下如果
$raw里只有data明文、没有sign,decode()只做解密不做验签(用于历史数据处理)。 回调场景请务必保证报文里有data和sign,否则伪造报文也能通过。
7. 主动验签 / 解密(对账、离线核对)
只做加签验签、不想走接口时,用 signer() 或 RsaHelper:
use Tansilu\HfPayLib\utils\RsaHelper;
// 1) 手工验证一段汇付报文(data 为 JSON 字符串,sign 为 Base64 签名)
$ok = RsaHelper::verify(RsaHelper::sort4JsonString($dataJson), $hfPublicKey, $sign);
// 2) 手工解密汇付返回的敏感字段
$mobile = RsaHelper::decrypt($cipherBase64, $merPrivateKey);
// 3) 批量加解密整个参数数组(只处理 SDK 约定的敏感字段)
$encrypted = RsaHelper::encryptFields($params, $hfPublicKey);
$plain = RsaHelper::decryptFields($encrypted, $merPrivateKey);
// 4) 用签名器(自动带上初始化时的配置)
$signer = $client->signer();
$signer->verify(['data' => $dataJson, 'sign' => $sign]); // bool
$signer->decode($dataJson); // 验签后解密为数组
// 5) 仅 RSA 模式:手工组装请求报文(prepare 只存在于 SignerRsaClient)
if ($signer instanceof \Tansilu\HfPayLib\library\impl\SignerRsaClient) {
$prepared = $signer->prepare($params, '10', '6666000100064457');
// ['data' => 排序后 JSON, 'sign' => Base64 签名, 'params' => 外层表单参数]
}
签名原文规则(与汇付官方 demo 一致):参数按 key 的 ascii 升序 → json_encode(JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)→ SHA256WithRSA。SDK 保证「发出去的 data」与「加签原文」是同一个字符串,含中文/URL 时不会被转义破坏。
8. 从 CFCA 迁移到 RSA 的检查清单
- 只改配置:把
sign_server改成rsa2,sign_file改成商户私钥路径,cert_file改成汇付公钥路径,sign_pwd留空(或用新键sign_type/mer_private_key/hf_public_key)。 - 确认服务器能读到私钥文件,且
php_openssl已开启。 - 业务代码零改动:
init()、$client->query()/trade()/...、new SignerHttpClient(...)、decode($raw)全部保持原样。 - 回调入库:RSA 回调是
data+sign(无check_value),回调入口需要把整包报文存下来再交给decode();验签字段校验也需从「check_value必填」改为「data、sign至少存在」。这是协议差异,只需改一次,之后 CFCA/RSA 来回切换都不用再动。 - 若出现
C00102 验证签名失败:检查私钥/公钥是否配反、是否用了测试环境秘钥、mid与秘钥是否同一商户。
响应与异常
底层响应对象 Tansilu\HfPayLib\http\Response
| 方法 | 说明 |
|---|---|
isSuccess() | HTTP 状态是否 2xx |
getCode() | HTTP 状态码 |
getSource() | 原始响应字符串 |
getBody() | 解析后的数组(RSA/CFCA 均为验签解密后的业务体) |
业务工厂方法通常直接返回对象(如 UnifiedOrder、WalletStatus),字段用属性读取:
$order->pay_url;
$status->resp_code;
异常
| 异常 | 触发场景 |
|---|---|
InitException | 配置缺失/非法(缺秘钥、缺签名服务器、sign_type 不支持) |
ParamsException | 必填业务参数缺失或格式不合法(本地校验,未发请求) |
SignException | 加签/验签/加解密失败,回调验签不通过 |
ApiException | 网络异常、HTTP 状态异常、响应结构异常(如缺 check_value) |
BizException | 汇付返回业务失败码,getCode() 为汇付返回码(如 C00009) |
try {
$client->trade()->closeOrder($orderId, $orderDate);
} catch (\Tansilu\HfPayLib\exception\BizException $e) {
echo $e->getCode(); // 汇付返回码
echo $e->getMessage(); // 返回描述
} catch (\Tansilu\HfPayLib\exception\SignException $e) {
// 签名/加解密问题
} catch (\Tansilu\HfPayLib\exception\ApiException $e) {
// 网络或响应异常
}
C00001(处理中)、C00002(已受理)不是终态,需要轮询查询接口;C00006(交易关闭)按业务处理。
接口一览
| 入口 | 工厂 | 主要方法 |
|---|---|---|
$client->market() | MarketFactory | create() 开户、walletManage() 钱包管理 |
$client->query() | QueryFactory | openStatus()、wallet()、trans()、bindCard()、balance()、record()、chainBalance() |
$client->manage() | ManageFactory | bindCashCard()、unBindCard()、fileDownload()、eCertificate() |
$client->trade() | TradeFactory | unifiedOrder()、delayDivideConfirm()、closeOrder()、refund()、refundGoods()、withdrawCash() |
$client->one() | OneLevelFactory | upload()、personalCreate()、companyCreate()、peddlarCreate() |
完整参数、返回码与开发约定见 docs/02-接口清单.md、docs/03-新增接口开发指南.md。
常见问题
Q:能同时兼容 PHP 7.4 和 PHP 8.x 吗?
可以,SDK 代码本身兼容 7.4(openssl_pkey_get_* 在不同版本返回 resource / 对象两种形态均已处理),依赖上分别使用 php-di ^6.4(7.4)与 php-di ^7.0(8.0+)。
Q:sign_type 只写 rsa 可以吗?
可以,SDK 内部会归一化为 rsa2。
Q:RSA 模式还需要 sign_server 吗?
不需要,本地私钥加签,不访问签名服务器。
Q:回调一直验签失败?
确认回调地址收的是汇付 POST 原始参数;RSA 必须同时有 data 和 sign,CFCA 必须由 check_value 传入远程签名服务器。参数被框架过滤/转义(如 magic_quotes、中间件改写 body)也会导致失败。
Q:HFPayClient 是单例,多商户怎么办?
getInstance() 返回同一实例,init() 会覆盖之前的配置。多商户建议按进程/请求隔离,不要在同一请求内切换多家商户配置。