认证与签名校验

对接说明

1. 平台所有接口基础路径为 https://zhcpay.net/api/payment
2. 所有请求采用 HTTPS 协议，统一使用 UTF-8 编码
3. 请求头必须携带 Authorization 字段，值为平台签发的 JWT Token

认证方式

所有接口需在 Header 中携带 JWT Token：

Authorization: <JWT Token>

Token 通过商户密钥签发，签名算法为 HS256。

如何获取 Token

Token 由平台为每个商户签发，请联系平台管理员获取。Token 中包含 mchId 信息。

统一响应码

code	含义
0	成功
40004	Token 无效
50002	请求失败
50004	订单不存在
50005	不支持的操作

异步通知签名校验

订单状态变更时，平台会向商户配置的 notifyUrl 推送通知。为防止伪造请求，请求头中包含 Authorization 签名字段，建议验证签名后再处理。

签名生成规则

1. 取 response body 作为签名基础字符串，例如：

{"code": "SUCCESS","mchId":"16952211552","orderNo":"20212211201220"}

2. 使用商户 Key，通过 HMAC-SHA256 算法计算签名，输出十六进制字符串

代码示例

Python

import hmac
import hashlib

def verify_push_msg(request_body, partner_key, authorization):
    cal_auth = hmac.new(
        partner_key.encode('utf-8'),
        request_body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return cal_auth == authorization

Go

package verify

import (
    "crypto/hmac"
    "crypto/sha256"
    "fmt"
)

func VerifyPushMsg(requestBody, partnerKey, authorization string) bool {
    h := hmac.New(sha256.New, []byte(partnerKey))
    h.Write([]byte(requestBody))
    calAuth := fmt.Sprintf("%x", h.Sum(nil))
    return authorization == calAuth
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;

public static Boolean verifyPushMsg(
    String requestBody, String partnerKey, String authorization
) throws Exception {
    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(
        partnerKey.getBytes("UTF-8"), "HmacSHA256"
    );
    sha256HMAC.init(secretKey);
    String result = Hex.encodeHexString(
        sha256HMAC.doFinal(requestBody.getBytes("UTF-8"))
    );
    return result.equals(authorization);
}

异步通知规则

1. 订单状态变更后，平台发送异步通知到商户 notifyUrl
2. 商户未收到通知时，系统会连续补发通知 8 次
3. 商户收到通知后，需返回字符串 success 终止补发
4. 建议校验请求头中的 Authorization 签名