Search by

tansilu / hfpay-lib

mothz

There is no license information available for the latest version (0.0.18) of this package.

Package info

git.tsl3060.com/tansilu/hfpay-lib.git

pkg:composer/tansilu/hfpay-lib

Statistics

Installs: 71

Dependents: 0

Suggesters: 0

0.0.18 2026-11-09 10:24 UTC

This package is auto-updated.

Last update: 2026-11-09 10:28:25 UTC


README

PHP SDK,封装汇付天下数字藏品(NFT)支付相关接口:开户、钱包、绑卡、查询、下单、分账、退款、取现、一级市场开户等。

  • 使用 PHP-DI 容器装配工厂,业务代码只面向 HFPayClient 单例
  • 支持两种签名方式:CFCA 远程签名服务器(默认,兼容老项目)与 RSA2 本地私钥加签
  • 两种签名方式对业务代码完全透明:只改配置,不改调用

详细文档见 docs/README.md。

环境要求

PHP 版本依赖组合状态
7.4guzzlehttp/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_filemer_private_key、hf_public_key(可用 sign_file/cert_file 旧键)
请求报文表单参数 + check_valueversion、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,便于只改环境变量完成切换。

配置项

公共

配置说明
debugtrue 走测试环境 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_pwdpfx 密码
cert_file签名服务器上的 cer 证书路径

RSA2 专有

配置说明
sign_typersa2 或 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 的检查清单

  1. 只改配置:把 sign_server 改成 rsa2,sign_file 改成商户私钥路径,cert_file 改成汇付公钥路径,sign_pwd 留空(或用新键 sign_type/mer_private_key/hf_public_key)。
  2. 确认服务器能读到私钥文件,且 php_openssl 已开启。
  3. 业务代码零改动:init()、$client->query()/trade()/...、new SignerHttpClient(...)、decode($raw) 全部保持原样。
  4. 回调入库:RSA 回调是 data + sign(无 check_value),回调入口需要把整包报文存下来再交给 decode();验签字段校验也需从「check_value 必填」改为「data、sign 至少存在」。这是协议差异,只需改一次,之后 CFCA/RSA 来回切换都不用再动。
  5. 若出现 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()MarketFactorycreate() 开户、walletManage() 钱包管理
$client->query()QueryFactoryopenStatus()、wallet()、trans()、bindCard()、balance()、record()、chainBalance()
$client->manage()ManageFactorybindCashCard()、unBindCard()、fileDownload()、eCertificate()
$client->trade()TradeFactoryunifiedOrder()、delayDivideConfirm()、closeOrder()、refund()、refundGoods()、withdrawCash()
$client->one()OneLevelFactoryupload()、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() 会覆盖之前的配置。多商户建议按进程/请求隔离,不要在同一请求内切换多家商户配置。