商户 API 接入文档
本文按商户接入顺序说明认证、代付下单、订单查询、余额查询和交易回单接口。所有示例使用当前上线的 HMAC-SHA256 协议;旧 ApiPost 文档中的 MD5/AES 示例已过时,当前接口不再接受。
1. 接入信息
| 项目 | 内容 |
|---|---|
| API 基础路径 | /index.php |
| 请求方式 | POST |
| 请求格式 | application/json; charset=utf-8 |
| 商户编码 | 管理后台分配的 customerCode |
| 商户密钥 | 已轮换的 32 字符商户 API 密钥 |
请将 API 基础路径拼接到你配置的 API 域名后,例如 https://你的API域名/index.php。请求来源 IP 必须先加入该商户的 API 可信 IP 列表。请使用 HTTPS,不要把商户密钥写入 URL、前端代码或日志。
2. 统一请求与签名
所有下列接口都使用同一外层结构:
{
"customerCode": "YOUR_CUSTOMER_CODE",
"signType": "HMAC-SHA256",
"data": {
"timestamp": 1794825600,
"nonce": "0123456789abcdef0123456789abcdef"
},
"sign": "64位小写十六进制HMAC签名"
}签名覆盖完整的 data 对象,外层 customerCode、signType 和 sign 不放进签名内容。data 必须包含:
| 字段 | 类型 | 要求 |
|---|---|---|
timestamp | integer 或十进制字符串 | Unix 时间戳,单位秒;与服务器时间相差不得超过 300 秒 |
nonce | string | 每次请求新生成,16–128 个 ASCII 字符,只能使用字母、数字、_、-;建议使用 32 位十六进制随机值 |
签名步骤:
- 递归按字典序升序排列
data中每个 JSON 对象的键;数组保留原顺序。 - 将规范化后的
data序列化为无空格 UTF-8 JSON:不转义 Unicode 和/,保留浮点数的小数形式。 - 使用商户密钥原始 UTF-8 字节计算
HMAC-SHA256(JSON字节, 商户密钥),输出 64 位小写十六进制字符串。 - 将结果放入外层
sign,并将signType固定为HMAC-SHA256。
同一个 nonce 只能使用一次;服务器使用 Redis 原子防重放。重试时请重新生成时间戳、nonce 和签名。金额建议用字符串传递,例如 "100.50",避免不同语言浮点数序列化差异。
PHP 签名示例
<?php
function canonicalize(mixed $value): mixed
{
if (!is_array($value)) {
return $value;
}
if (array_is_list($value)) {
foreach ($value as $index => $item) {
$value[$index] = canonicalize($item);
}
return $value;
}
foreach ($value as $key => $item) {
$value[$key] = canonicalize($item);
}
ksort($value, SORT_STRING);
return $value;
}
function signData(array $data, string $secretKey): string
{
$json = json_encode(
canonicalize($data),
JSON_UNESCAPED_SLASHES
| JSON_UNESCAPED_UNICODE
| JSON_PRESERVE_ZERO_FRACTION
| JSON_THROW_ON_ERROR
);
return hash_hmac('sha256', $json, $secretKey);
}
$data = [
'timestamp' => time(),
'nonce' => bin2hex(random_bytes(16)),
'notifyUrl' => 'https://merchant.example/notify',
'transfer' => [
'transOrderNo' => 'ORDER' . date('YmdHis'),
'transType' => '1',
'transName' => '收款人',
'transAccount' => '收款账号',
'transAmount' => '100.50',
],
];
$request = [
'customerCode' => 'YOUR_CUSTOMER_CODE',
'signType' => 'HMAC-SHA256',
'data' => $data,
'sign' => signData($data, 'YOUR_SECRET_KEY'),
];
// 使用 HTTPS POST JSON 请求:POST /index.php/api/Transfer/transferJava 签名示例
示例使用 Jackson 序列化 JSON,HMAC 使用 JDK 自带的 javax.crypto。项目若使用 Maven,可通过现有依赖管理引入 jackson-databind;无需额外的摘要算法依赖。
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.SecureRandom;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
public final class MerchantApiSigner {
private static final ObjectMapper JSON = new ObjectMapper();
private static final SecureRandom RANDOM = new SecureRandom();
private MerchantApiSigner() {}
private static Object canonicalize(Object value) {
if (value instanceof Map<?, ?>) {
Map<?, ?> input = (Map<?, ?>) value;
Map<String, Object> sorted = new TreeMap<>();
for (Map.Entry<?, ?> entry : input.entrySet()) {
if (!(entry.getKey() instanceof String)) {
throw new IllegalArgumentException("JSON object keys must be strings");
}
sorted.put((String) entry.getKey(), canonicalize(entry.getValue()));
}
return sorted;
}
if (value instanceof List<?>) {
List<Object> ordered = new ArrayList<>();
for (Object item : (List<?>) value) {
ordered.add(canonicalize(item));
}
return ordered;
}
return value;
}
public static String signData(Map<String, Object> data, String secretKey)
throws JsonProcessingException, GeneralSecurityException {
byte[] message = JSON.writeValueAsBytes(canonicalize(data));
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] digest = mac.doFinal(message);
StringBuilder hex = new StringBuilder(digest.length * 2);
for (byte b : digest) {
hex.append(String.format("%02x", b & 0xff));
}
return hex.toString();
}
private static String newNonce() {
byte[] bytes = new byte[16];
RANDOM.nextBytes(bytes);
StringBuilder hex = new StringBuilder(bytes.length * 2);
for (byte b : bytes) {
hex.append(String.format("%02x", b & 0xff));
}
return hex.toString();
}
public static void main(String[] args) throws Exception {
String customerCode = "YOUR_CUSTOMER_CODE";
String secretKey = "YOUR_SECRET_KEY"; // 从安全配置读取,不要写入源码
Map<String, Object> transfer = new LinkedHashMap<>();
transfer.put("transOrderNo", "ORDER" + System.currentTimeMillis());
transfer.put("transType", "1");
transfer.put("transName", "收款人");
transfer.put("transAccount", "收款账号");
transfer.put("transAmount", "100.50"); // 金额建议使用字符串,避免浮点序列化差异
Map<String, Object> data = new LinkedHashMap<>();
data.put("timestamp", Instant.now().getEpochSecond());
data.put("nonce", newNonce());
data.put("notifyUrl", "https://merchant.example/notify");
data.put("transfer", transfer);
Map<String, Object> request = new LinkedHashMap<>();
request.put("customerCode", customerCode);
request.put("signType", "HMAC-SHA256");
request.put("data", data);
request.put("sign", signData(data, secretKey));
// 使用支持 TLS 的 HTTP 客户端发送:POST /index.php/api/Transfer/transfer
System.out.println(JSON.writeValueAsString(request));
}
}Jackson 默认输出紧凑 JSON、UTF-8 字节且不转义 / 和普通 Unicode 字符,与本协议的序列化规则一致。对象键由示例代码递归排序,列表保留顺序。不要将 secretKey 写入日志或打印到控制台;生产环境应从密钥管理或受限环境配置读取。
3. 代付下单
接口: POST /api/Transfer/transfer
说明: 创建一笔代付订单。转账类型支持支付宝、个人银行卡和对公银行卡。
data 业务字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
notifyUrl | string | 是 | 商户回调地址;必须为可从公网访问的 HTTPS 域名地址,证书有效,不能依赖 HTTP 重定向;仅允许 443/8443 端口 |
transfer | object | 是 | 单笔转账信息 |
transfer.productCode | string | 是 | 商户已获授权的产品编码;由平台提供 |
transfer.transOrderNo | string | 是 | 商户订单号;同一商户下必须唯一,不可复用 |
transfer.transType | string | 是 | 1 支付宝;2 个人银行卡;3 对公银行卡 |
transfer.transAmount | string/number | 是 | 转账金额,必须大于 0,并符合商户单笔限额 |
transfer.transAccount | string | 是 | 收款账号;银行卡类型须为数字且至少 12 位 |
transfer.transName | string | 是 | 收款人姓名 |
transfer.transOrderRemark | string | 否 | 转账备注;允许中文、字母、数字、下划线、连字符和 · |
transfer.instName | string | 对公必填 | 开户行名称 |
transfer.instProvince | string | 对公必填 | 开户行省份 |
transfer.instCity | string | 对公必填 | 开户行城市 |
transfer.instBranchName | string | 对公必填 | 开户支行名称 |
transfer.bankCode | string | 对公必填 | 联行号 |
productCode 必须是平台分配且已授权给该商户的产品编码。回调域名必须解析到公网地址;不支持 IP 字面量、内网地址或带用户名/密码的 URL。
{
"customerCode": "YOUR_CUSTOMER_CODE",
"signType": "HMAC-SHA256",
"data": {
"timestamp": 1794825600,
"nonce": "0123456789abcdef0123456789abcdef",
"notifyUrl": "https://merchant.example/notify",
"transfer": {
"productCode": "PRODUCT_CODE",
"transOrderNo": "ORDER202611170001",
"transType": "1",
"transAmount": "100.50",
"transAccount": "收款账号",
"transName": "收款人",
"transOrderRemark": "货款"
}
},
"sign": "按完整data计算"
}成功响应:
{
"code": 1,
"data": "批次号",
"msg": "ok"
}响应中的 data 是平台批次号,不代表代付已完成。请通过订单查询接口获取订单状态,并以订单终态为准。
4. 订单查询
接口: POST /api/Transfer/query
在统一 data 中除 timestamp、nonce 外传入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
shopOrderNum | string | 是 | 下单时使用的商户订单号;只能查询本商户订单 |
成功响应 data:
| 字段 | 说明 |
|---|---|
shopOrderNum | 商户订单号 |
orderNum | 平台订单号 |
orderMoney | 订单金额 |
transferState | 状态:0 待处理、1 处理中、2 成功、3 失败、4 退票 |
transferTime | 转账时间 |
transferType | 转账类型:1 支付宝、2 个人银行卡、3 对公银行卡 |
failureReason | 失败原因;无失败原因时为空字符串 |
{
"code": 1,
"data": {
"shopOrderNum": "ORDER202611170001",
"orderNum": "平台订单号",
"orderMoney": "100.50",
"transferState": 1,
"transferTime": 0,
"transferType": 1,
"failureReason": ""
},
"msg": "ok"
}5. 查询商户余额
接口: POST /api/Transfer/balance
data 只需包含统一认证字段 timestamp 和 nonce。成功响应中的 data 是商户可用余额(字符串,单位元):
{
"code": 1,
"data": "10.85",
"msg": "ok"
}6. 交易回单
回单能力取决于订单支付渠道及上游支持情况。订单必须属于当前商户并满足渠道回单条件。
6.1 申请回单
接口: POST /api/Transfer/billApply
data 业务字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
shopOrderNum | string | 是 | 商户订单号 |
成功响应 data 是上游回单文件 ID(fileId):
{"code":1,"data":"FILE_ID","msg":"ok"}6.2 查询回单下载链接
接口: POST /api/Transfer/billQuery
data 业务字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
shopOrderNum | string | 是 | 商户订单号 |
fileId | string | 是 | 申请回单时返回的文件 ID |
成功响应 data 是下载 URL。URL 非永久有效,请及时下载并安全保存:
{"code":1,"data":"https://download.example/temporary-url","msg":"ok"}7. 订单结果回调
订单进入成功、失败或退票等终态后,平台会向下单时的 notifyUrl 发送 JSON POST。回调数据按第 2 节相同规则使用 HMAC-SHA256 签名;上线切换后,历史未确认回调也使用当前商户密钥和 HMAC-SHA256。
回调 data 字段:
| 字段 | 说明 |
|---|---|
orderNum | 平台订单号 |
shopOrderNum | 商户订单号 |
transferState | 0 待处理、1 处理中、2 成功、3 失败、4 退票 |
transferTime | 转账时间戳 |
transferMoney | 转账金额 |
alipayOrderNum | 支付宝订单号;不适用时可能为空 |
alipayPayFundOrderNum | 支付宝资金流水号;不适用时可能为空 |
failureReason | 失败原因;仅失败时出现 |
failureCode | 失败原因编码;仅失败时出现 |
timestamp、nonce | 本次回调的时间戳和随机数 |
回调结构示例(签名值仅作占位):
{
"customerCode": "YOUR_CUSTOMER_CODE",
"signType": "HMAC-SHA256",
"data": {
"orderNum": "平台订单号",
"shopOrderNum": "ORDER202611170001",
"transferState": 2,
"transferTime": 1794825600,
"transferMoney": "100.50",
"alipayOrderNum": "上游订单号",
"alipayPayFundOrderNum": "资金流水号",
"timestamp": 1794825600,
"nonce": "0123456789abcdef0123456789abcdef"
},
"sign": "按完整data计算"
}验签成功后应先按 orderNum 或 shopOrderNum 幂等更新本地订单,再返回 HTTP 200,响应正文严格为 success。重复回调不得重复执行付款、记账等业务。其他响应内容或非 200 状态会被视为未确认,平台可能重试。
8. 错误处理与重试
成功业务响应使用 code: 1;业务失败通常返回 code: 0 和 msg。常见失败包括:商户 IP 未加入白名单、商户或产品不可用、签名类型/签名错误、时间戳过期、nonce 重放、参数错误、商户额度不足、订单号重复或订单不属于当前商户。HTTP 状态码与响应正文都应检查。
- 签名错误、时钟偏差、nonce 重复:修正请求后重新签名;每次重试使用全新 nonce。
- 下单超时:不要立即用新订单号重下。先使用原商户订单号查询,以免产生重复付款。
- 查单结果为处理中:稍后查询;不要把收到批次号当成付款成功。
code: 0:读取msg并按错误原因处理;不要根据本地猜测将失败订单改成成功。
9. 旧版 ApiPost 文档差异
参考 ApiPost 页面中的 MD5 签名方式和 signType: MD5 已停用。当前请求与回调必须使用 signType: HMAC-SHA256、新商户密钥、300 秒时间窗和一次性 nonce。商户应在恢复业务前完成下单签名、查单签名以及回调验签升级。