1. 微信服务商API
新运微信服务商API
  • 微信服务商API
    • 新运微信服务商API
    • 签名生成详细规则
    • 错误码文档
    • 微工卡接入流程
    • 批量转账
      • 批量转账（创建批次）
      • 查询批量转账状态（out_batch_no）
      • 查询批量转账状态（batch_id）
      • 查询批量转账明细（out_batch_no）
      • 查询批量转账明细（batch_id）
      • 查询批量转账明细（微信分页 wrapper）
      • 查询批量转账明细（batch_id，微信分页 wrapper）
    • 微工卡
      • 查询微工卡授权状态
      • 生成微工卡授权token
      • 查询核身结果
      • 拉起微工卡（授权并使用）
      • 拉起微工卡（查看我的微工卡）
      • 微工卡核身预下单（正式）
      • 微工卡批量转账（创建批次）
      • 微工卡批量转账（查询批次状态）
      • 微工卡批量转账（查询批次明细）
      • 微工卡批量转账电子回单受理（占位）
      • 微工卡批量转账电子回单状态（内部原始记录）
      • 微工卡批量转账电子回单下载链接
    • 商户回调
      • 批次状态变化回调（平台 -> 商户）
    • 数据模型
      • Schemas
        • ApiResponse_Error
        • ApiResponse_WechatError
        • ApiResponse_String
        • ApiResponse_BatchTransferResponse
        • ApiResponse_QueryBatchTransferResponse
        • ApiResponse_TransferDetailResponseList
        • ApiResponse_QueryBatchTransferDetailsResponse
        • ApiResponse_PayrollAuthTokenResponse
        • ApiResponse_PayrollAuthStatusResponse
        • ApiResponse_PayrollLaunchResponse
        • ApiResponse_PayrollFaceVerify
        • ApiResponse_BatchTransferRecord
        • ApiResponse_BatchTransferDetailList
        • WechatNotifyResponse
        • BatchTransferResponse
        • QueryBatchTransferResponse
        • TransferDetailResponse
        • QueryBatchTransferDetailsResponse
        • CreatePartnerTransferBatchRequest
        • CreatePayrollTransferBatchRequest
        • PayrollAuthTokenRequest
        • PayrollAuthTokenResponse
        • PayrollAuthStatusResponse
        • PayrollLaunchResponse
        • PayrollFacePreorderRequest
        • PayrollFaceVerify
        • BatchTransferRecord
        • BatchTransferCallbackDTO
      • Response
        • BadRequest
        • Unauthorized
        • Forbidden
        • NotFound
        • Conflict
        • RateLimitExceeded
        • WechatPayError
  1. 微信服务商API

签名生成详细规则

本文档描述 客户侧调用平台接口 的签名生成规则（HMAC-SHA256），需与服务端 SignatureValidator.buildDataToSign() 完全一致。
📖 相关文档：签名失败时请参考 错误码文档 中的"签名相关错误码 (2000-2099)"章节。

1. 必须携带的请求头（新优先，旧兼容）#

调用所有需要验签的接口时，请在 HTTP Header 中携带：
X-Client-Id：客户/应用 ID（推荐）
X-Biz-Merchant-Id：业务方商户 ID（推荐）
X-Timestamp：毫秒级时间戳（13 位），与服务端误差不超过 5 分钟
X-Nonce：随机字符串，长度 ≤ 128，只能使用一次（服务端缓存 5 分钟防重）
X-Signature：签名结果（小写 16 进制字符串）
兼容期内可同时双发旧头（可选）：
X-App-Id：旧版客户/应用 ID（等同 X-Client-Id）
X-Merchant-Id：旧版业务方商户 ID（等同 X-Biz-Merchant-Id）
服务端读取优先级：X-Client-Id > X-App-Id；X-Biz-Merchant-Id > X-Merchant-Id。

2. 待签名字符串 dataToSign 拼接规则（LF 换行）#

服务端使用如下顺序拼接待签名字符串（\n 表示换行符，必须是 LF）：
1.
HTTP Method（全部大写）
2.
请求路径 Path（不含域名与查询串；等同服务端 request.getRequestURI()）
3.
时间戳 X-Timestamp
4.
随机串 X-Nonce
5.
客户/应用 ID（X-Client-Id 或 X-App-Id）
6.
业务方商户 ID（X-Biz-Merchant-Id 或 X-Merchant-Id）
7.
请求体 MD5（小写 32 位 16 进制）。如果请求体为空/空白，则这一行为空行
8.
排序后的查询参数字符串（格式：k1=v1&k2=v2）
非常关键（与服务端完全一致）：
第 7 行之后一定有一个换行符（即使 body 为空，仍然会有一个结尾换行）
第 8 行（query string）只有在存在非空 query 参数时才追加；如果没有 query 参数，不会再追加任何内容（也不会多一个换行）
示例结构（仅示意换行）：
METHOD\n
/request/path\n
TIMESTAMP\n
NONCE\n
CLIENT_ID\n
BIZ_MERCHANT_ID\n
BODY_MD5_OR_EMPTY\n
QUERY_STRING(可选，无则不追加)

2.1 请求体 MD5#

对 原始请求体字符串（UTF-8）计算 MD5，输出小写 32 位 16 进制
若 body 为 null / "" / 全空白（只含空格、换行等），服务端视为 空请求体，第 7 行为空行

2.2 查询参数排序与过滤#

提取所有 query 参数，按参数名升序排序（字典序）
服务端会 忽略 value 为空/空白 的参数
生成格式：k1=v1&k2=v2（中间用 & 连接）

3. 签名算法（HMAC-SHA256）#

1.
获取平台分配的 apiSecret
2.
按第 2 节构造 dataToSign
3.
计算：signature = HMAC_SHA256(apiSecret, dataToSign)
4.
转成 小写 16 进制，写入 X-Signature

4. 校验限制#

时间戳容差：≤ 5 分钟（默认）
Nonce 防重：5 分钟内相同 nonce+timestamp 只能使用一次
签名比较：按小写 16 进制字符串比较

5. 示例#

5.1 GET 请求（带 query 参数）#

以 GET /api/v1/partner-transfer/batch/status?outBatchNo=BATCH123 为例：
Method：GET
Path：/api/v1/partner-transfer/batch/status
Query：outBatchNo=BATCH123
Body：空
Timestamp：1730987654321
Nonce：a1b2c3d4e5f6g7h8
ClientId：wx1234567890
BizMerchantId：M1234567890
待签名字符串：
GET
/api/v1/partner-transfer/batch/status
1730987654321
a1b2c3d4e5f6g7h8
wx1234567890
M1234567890

outBatchNo=BATCH123

5.2 POST 请求（带 JSON body）#

以 POST /api/v1/partner-transfer/batch/create 为例：
Method：POST
Path：/api/v1/partner-transfer/batch/create
Query：无
Body：{"subMchid":"1900000109","outBatchNo":"BATCH20250101","batchName":"测试","batchRemark":"备注","totalAmount":100,"totalNum":1,"transferDetailList":[{"outDetailNo":"D001","transferAmount":100,"transferRemark":"转账","openid":"oXXXX"}]}
Timestamp：1730987654321
Nonce：a1b2c3d4e5f6g7h8
ClientId：wx1234567890
BizMerchantId：M1234567890
Body MD5 计算：
MD5(原始 body 字符串) = "e4d909c290d0fb1ca068ffaddf22cbd0"  // 示例值
待签名字符串（注意：无 query 时第 8 行不追加）：
POST
/api/v1/partner-transfer/batch/create
1730987654321
a1b2c3d4e5f6g7h8
wx1234567890
M1234567890
e4d909c290d0fb1ca068ffaddf22cbd0
⚠️ 重要：POST 请求必须设置 Content-Type: application/json，且 Body MD5 计算的是发送的原始字符串（UTF-8 编码），不要格式化或压缩 JSON。

5.3 cURL 完整示例#

6. Java 示例#

说明：示例使用 commons-codec。注意 空 query 不追加、空 body 仍有结尾换行。

Maven 依赖#

<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.15</version>
</dependency>

签名工具类#

7. 常见问题#

场景排查建议
签名不匹配优先核对：Path 是否只包含 URI、换行规则、query 是否按 key 排序且忽略空值、body 是否完全一致（含空白）
时间戳错误确认 13 位毫秒时间戳；同步机器时间
Nonce 重复每次请求生成新的随机串（≤ 128）
query 参与不一致确认签名时参与了所有非空 query 参数
body 参与不一致body 参与 MD5 的字符串必须与实际发送的完全一致（包含空格/换行）
IP 不允许确认客户侧出口 IP 在平台配置白名单内
权限错误确认 clientId + bizMerchantId 已开通对应 API 权限

8. 调试技巧#

8.1 打印待签名字符串#

签名不匹配时，最有效的排查方式是打印客户端生成的 dataToSign，与服务端日志对比。

8.2 常见换行问题#

问题正确做法
Windows 换行符 \r\n必须使用 LF（\n），不能用 CRLF
Body 为空时漏掉换行第 7 行必须有换行，即使 body 为空也要 sb.append("\n")
Query 为空时多加换行无 query 参数时不追加第 8 行，不要多加换行
JSON 格式化Body MD5 计算必须用原始字符串，不能格式化/美化 JSON

8.3 签名失败错误码#

错误码含义排查方向
SIGNATURE_MISSING缺少签名头检查 Header 是否完整
SIGNATURE_INVALID签名不匹配打印 dataToSign 对比
TIMESTAMP_INVALID时间戳过期同步服务器时间
NONCE_DUPLICATE随机数重复每次请求生成新 nonce
IP_NOT_ALLOWEDIP 不在白名单联系管理员添加 IP
📖 完整错误码列表请参考 错误码文档
修改于 2026-01-08 09:41:41
上一页
新运微信服务商API
下一页
错误码文档
Built with