商户 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 必须包含:

字段类型要求
timestampinteger 或十进制字符串Unix 时间戳,单位秒;与服务器时间相差不得超过 300 秒
noncestring每次请求新生成,16–128 个 ASCII 字符,只能使用字母、数字、_、-;建议使用 32 位十六进制随机值

签名步骤:

  1. 递归按字典序升序排列 data 中每个 JSON 对象的键;数组保留原顺序。
  2. 将规范化后的 data 序列化为无空格 UTF-8 JSON:不转义 Unicode 和 /,保留浮点数的小数形式。
  3. 使用商户密钥原始 UTF-8 字节计算 HMAC-SHA256(JSON字节, 商户密钥),输出 64 位小写十六进制字符串。
  4. 将结果放入外层 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/transfer

Java 签名示例

示例使用 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 业务字段:

字段类型必填说明
notifyUrlstring是商户回调地址;必须为可从公网访问的 HTTPS 域名地址,证书有效,不能依赖 HTTP 重定向;仅允许 443/8443 端口
transferobject是单笔转账信息
transfer.productCodestring是商户已获授权的产品编码;由平台提供
transfer.transOrderNostring是商户订单号;同一商户下必须唯一,不可复用
transfer.transTypestring是1 支付宝;2 个人银行卡;3 对公银行卡
transfer.transAmountstring/number是转账金额,必须大于 0,并符合商户单笔限额
transfer.transAccountstring是收款账号;银行卡类型须为数字且至少 12 位
transfer.transNamestring是收款人姓名
transfer.transOrderRemarkstring否转账备注;允许中文、字母、数字、下划线、连字符和 ·
transfer.instNamestring对公必填开户行名称
transfer.instProvincestring对公必填开户行省份
transfer.instCitystring对公必填开户行城市
transfer.instBranchNamestring对公必填开户支行名称
transfer.bankCodestring对公必填联行号

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 外传入:

字段类型必填说明
shopOrderNumstring是下单时使用的商户订单号;只能查询本商户订单

成功响应 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 业务字段:

字段类型必填说明
shopOrderNumstring是商户订单号

成功响应 data 是上游回单文件 ID(fileId):

{"code":1,"data":"FILE_ID","msg":"ok"}

6.2 查询回单下载链接

接口: POST /api/Transfer/billQuery

data 业务字段:

字段类型必填说明
shopOrderNumstring是商户订单号
fileIdstring是申请回单时返回的文件 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商户订单号
transferState0 待处理、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 状态码与响应正文都应检查。

9. 旧版 ApiPost 文档差异

参考 ApiPost 页面中的 MD5 签名方式和 signType: MD5 已停用。当前请求与回调必须使用 signType: HMAC-SHA256、新商户密钥、300 秒时间窗和一次性 nonce。商户应在恢复业务前完成下单签名、查单签名以及回调验签升级。