1. 认证方式
使用API Key进行认证时，需要在请求头中添加以下信息：
Authorization: ApiKey {api_key}
Signature: {signature}其中：
- Authorization：API Key认证头，格式为
ApiKey {api_key} - Signature：请求签名（必填），用于验证请求数据的完整性
请先创建开放平台配置，才能收到平台回调通知。
使用API Key进行认证时，需要在请求头中添加以下信息：
Authorization: ApiKey {api_key}
Signature: {signature}其中：
ApiKey {api_key}签名用于验证请求数据的完整性，防止数据被篡改。签名生成步骤：
sign 参数、null 值、空字符串、空数组、空对象sort_keys=true，separators=(',', ':')）UTF-8编码）key1=value1&key2=value2Signature 中# 原始请求数据
{
"account_book_id": "123456",
"amount": "100.00",
"payee_info": {
"identity_type": "ALIPAY_ACCOUNT",
"name": "张三",
"identity": "zhangsan@example.com"
},
"sign": "不需要参与签名",
"empty_param": "",
"null_param": null
}
# 1. 过滤后（排除sign、空字符串、null）
{
"account_book_id": "123456",
"amount": "100.00",
"payee_info": {
"identity_type": "ALIPAY_ACCOUNT",
"name": "张三",
"identity": "zhangsan@example.com"
}
}
# 2. 按参数名升序排序
account_book_id, amount, payee_info
# 3. JSON序列化嵌套对象
payee_info={"identity":"zhangsan@example.com","identity_type":"ALIPAY_ACCOUNT","name":"张三"}
# 4. URL编码（处理中文）
name=%E5%BC%A0%E4%B8%89
# 5. 拼接字符串
account_book_id=123456&amount=100.0&payee_info=%7B%22identity%22%3A%22zhangsan%40example.com%22%2C%22identity_type%22%3A%22ALIPAY_ACCOUNT%22%2C%22name%22%3A%22%E5%BC%A0%E4%B8%89%22%7D
# 6. HMAC-SHA256签名（密钥为API Secret）
signature = HMAC-SHA256(api_secret, sign_str)
# 7. 请求头中添加签名
Signature: {signature}sign参数、null值、空字符串、空数组、空对象payee_info）会先进行JSON序列化再参与签名从资金账户转账到支付宝账户/银行卡
POST https://api.qcsj88888.com/payment/openapi/account/transfer
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| account_book_id | string | 是 | 付款方资金账户号 |
| amount | string | 是 | 转账金额，单位为元，精确到小数点后两位，大于0.02元 |
| order_title | string | 否 | 转账标题 |
| remark | string | 否 | 转账备注 |
| third_biz_no | string | 是 | 三方订单号（商户侧唯一标识，不可重复） |
| payee_info | object | 是 |
curl -X POST 'https://api.qcsj88888.com/payment/openapi/account/transfer' \
-H 'Authorization: ApiKey your_api_key' \
-H 'Signature: your_signature' \
-H 'Content-Type: application/json' \
-d '{
"account_book_id": "资金账号",
"amount": "100.00",
"order_title": "转账标题",
"third_biz_no": "商户订单号202604270001",
"payee_info": {
"identity_type": "ALIPAY_ACCOUNT",
"name": "收款人姓名",
"identity": "收款人支付宝账号"
}
}'{"code": 200, "message": "转账申请已提交", "data": {"status": "DEALING", "order_no": "2026042711122334455", "third_biz_no": "商户订单号202604270001"}}根据三方订单号查询转账状态和详情
POST https://api.qcsj88888.com/payment/openapi/account/transfer/query
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| third_biz_no | string | 是 | 三方订单号（发起转账时传入的商户侧唯一标识） |
curl -X POST 'https://api.qcsj88888.com/payment/openapi/account/transfer/query' \
-H 'Authorization: ApiKey your_api_key' \
-H 'Signature: your_signature' \
-H 'Content-Type: application/json' \
-d '{
"third_biz_no": "商户订单号202604270001"
}'{
"code": 200,
"message": "查询成功",
"data": {
"status": "SUCCESS",
"order_no": "2026042711122334455",
"amount": "100.00",
"payee_info": {
"identity_type": "ALIPAY_ACCOUNT",
"name": "张*",
"identity": "z****@example.com"
},
"created_time": "2026-04-27 11:22:33",
"updated_time": "2026-04-27 11:25:45"
}
}| 状态码 | 描述 |
|---|---|
| DEALING | 处理中 |
| SUCCESS | 成功 |
| FAIL | 失败 |
| REFUND | 已退款 |
查询指定企业资金专户的余额信息
POST https://api.qcsj88888.com/payment/openapi/account/balance/query
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| enterprise_id | string | 是 | 企业ID（在支付宝企业码平台注册的企业唯一标识） |
curl -X POST 'https://api.qcsj88888.com/payment/openapi/account/balance/query' \
-H 'Authorization: ApiKey your_api_key' \
-H 'Signature: your_signature' \
-H 'Content-Type: application/json' \
-d '{
"enterprise_id": "2088480777900000"
}'{
"code": 200,
"message": "查询成功",
"data": [
{
"account_book_id": "2088480770900000",
"available_amount": "50000.00",
"enable_status": "ENABLE",
"scene": "B2B_TRANS",
"account_card_info": {
"card_no": "xxxx",
"bank_name": "招商银行"
}
}
]
}| 字段名 | 类型 | 描述 |
|---|---|---|
| account_book_id | string | 资金专户号 |
| available_amount | string | 可用余额（单位：元，精确到小数点后两位） |
| enable_status | string | 启用状态：ENABLE（启用）/ DISABLE（禁用） |
| scene | string | 场景类型：B2B_TRANS（B2B转账） |
| account_card_info | object | 账户卡信息（银行卡号、银行名称等） |
scene 为 B2B_TRANS 的资金专户当转账状态发生变化时，系统会主动向商户配置的回调地址发送通知。
系统按照以下优先级获取回调地址：
说明：如果 API Key 已配置回调地址，则优先使用；否则使用开放平台配置中的回调地址。
| 参数名 | 类型 | 描述 |
|---|---|---|
| notify_id | string | 通知ID，唯一标识 |
| timestamp | int | 通知时间戳（毫秒） |
| content | string | JSON格式的通知内容 |
| 参数名 | 类型 | 描述 |
|---|---|---|
| status | string | 转账状态：DEALING（处理中）、SUCCESS（成功）、FAIL（失败）、REFUND（已退款） |
| order_no | string | 平台订单号 |
| third_biz_no | string | 商户订单号（发起转账时传入的三方订单号） |
| amount | number | 转账金额（元） |
| created_time | string | 创建时间 |
| updated_time | string | 更新时间 |
POST /your/callback/url HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
------WebKitFormBoundary
Content-Disposition: form-data; name="notify_id"
n1234567890123456789
------WebKitFormBoundary
Content-Disposition: form-data; name="timestamp"
1715767200000
------WebKitFormBoundary
Content-Disposition: form-data; name="content"
{
"status": "SUCCESS",
"order_no": "2026042711122334455",
"third_biz_no": "商户订单号202604270001",
"amount": "100.00",
"created_time": "2026-04-27 11:22:33",
"updated_time": "2026-04-27 11:25:45"
}
------WebKitFormBoundary--商户服务端收到通知后，需要返回 HTTP 200 状态码表示成功接收。如果返回非 200 状态码或超时，系统会进行重试。
<?php
class SignatureGenerator
{
private static function ksortRecursive(&$array) {
if (!is_array($array)) return;
ksort($array, SORT_STRING);
foreach ($array as &$value) {
self::ksortRecursive($value);
}
}
public static function generateSignature(
string $apiSecret,
array $requestData,
array $excludeParams = ['sign']
): string {
$filteredData = [];
foreach ($requestData as $key => $value) {
if (in_array($key, $excludeParams, true)) {
continue;
}
if ($value === null || $value === '') {
continue;
}
if (is_array($value) && empty($value)) {
continue;
}
$filteredData[$key] = $value;
}
self::ksortRecursive($filteredData);
$collect = [];
foreach ($filteredData as $key => $value) {
if (is_array($value)) {
$value = json_encode($value, JSON_UNESCAPED_SLASHES);
}
$encodedValue = rawurlencode((string)$value);
$collect[] = "{$key}={$encodedValue}";
}
$signStr = implode('&', $collect);
return hash_hmac('sha256', $signStr, $apiSecret);
}
public static function verifySignature(
string $apiSecret,
array $requestData,
string $signature
): bool {
$expectedSignature = self::generateSignature($apiSecret, $requestData);
return hash_equals($expectedSignature, $signature);
}
}
// ================= 测试调用 =================
$apiSecret = 'your_api_secret_here';
$requestData = [
"account_book_id" => "2088480770900000",
"amount" => "1.00",
"order_title" => "Apikey转账",
"third_biz_no" => "1234242026042700111",
"payee_info" => [
"identity_type" => "ALIPAY_ACCOUNT",
"name" => "钱先生",
"identity" => "1xx9xx9xxxxx"
]
];
// 生成签名
$signature = SignatureGenerator::generateSignature($apiSecret, $requestData);
echo "生成的签名: {$signature}\n";
// 验证签名
$isValid = SignatureGenerator::verifySignature($apiSecret, $requestData, $signature);
echo "签名验证结果: " . ($isValid ? '有效' : '无效') . "\n";
?>