签名算法

请花两分钟阅读接口调用说明及约定，避免在对接过程中遇到不必要的麻烦。

• 对接时需要使用到接口密钥，您可以从商户后台获取
• 接口路径前缀中的域名部分，请向客服索取

调用风格

POST 请求的接口只接受 JSON 数据，请在 HTTP 请求头中将 content-type 设置为 application/json。当前接口只返回 JSON 数据格式。

参数分类

调用时参数在不同的位置，有不同的称呼。如以下 URL：

http://api.demo.com/[path_param]?query_param=1

其中：

• [path_param]称为Path参数(路径参数)
• query_param称为Query参数(查询参数)
• 当请求为 POST 时，通过 Body 传递的参数，称为Body参数(请求体参数)

固定参数

接口调用时需要提供以下固定参数，这部分参数是每次调用都必须带上

• nonce: 随机字符串，32 个字符以内
• timestamp: 10 位长度的 UNIX 时间戳
• sign: 参数签名

请求响应

接口调用后响应内容结构如下：

{
  "code": 200,
  "payload": {
    "id": "E123456789A",
    "orderUrl": "",
    "channel": "alipay",
    "others": "..."
  }
}

接口调用成功与否，可以根据 code 状态码判断。成功时 code 为 200，失败时 code 为 200。失败时，HTTP 响应体中将提供一个 message 字段表明错误原因。

请求失败案例

请求下单时提供的参数签名错误，将返回以下内容

{
  "code": 400,
  "errors": {
    "message": "签名校验失败"
  }
}

目前仅返回一个错误代码: 400。

请求成功案例

请求下单成功时，将返回以下内容

{
  "code": 200,
  "payload": {
    "id": "E5df79e7fec2cef205f62d520",
    "trans_id": "TeOfB7HwJRsSiCyd5",
    "amount": "200.00",
    "channel": "alipay",
    "status": 0,
    "url": "http://cashier.demo.com/cashier/order?id=E5df79e7fec2cef205f62d520"
  }
}

签名算法

在调用接口前，需要对接口参数进行签名。接口支持 MD5 与 RSA 两种签名算法。默认签名算法为 MD5，若需要使用 RSA 签名，请将 alg 设置为 rsa。注意参数有可能新增，所请务必将除 sign 之外的所有参数进行签名。

MD5 签名

• 设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照参数名 ASCII 码从小到大排序（字典排序）
• 使用 URL 键值对的格式，即 key1=value1&key2=value2…，拼接成字符串。注意：空值参数不参与签名
• 将接口密钥放置在第 1 步中的字符串前面，用「&」合并在一起
• 使用 md5 计算上一步中的字符串摘要(不区分大小写)，将此摘要以 sign 参数一并传递给接口

例如，某 POST 接口调用时参数如下，API Token 假设为：xoJb3BS8j40OCuPc6kzE：

{
  "mch_id": "M3pZtGCTQg7rJeoLy",
  "trans_id": 20181230213948,
  "amount": "200.00",
  "channel": "alipay",
  "remarks": "memo",
  "nonce": "7886356ioiasdf",
  "timestamp": 1678132123,
  "callback_url": "http://hd3tcp.javawebdata9.com/api/recharge/onlinePayAsyncCallback/20200627132036809474",
  "ip": "47.244.122.36"
}

按前文所述的算法，拼接后结果如下（注意，若有 Path 参数，需要将 Path 参数一并按字典排序并合并成字符串，并且空参数不参与签名）：

xoJb3BS8j40OCuPc6kzE&amount=200.00&callback_url=http://hd3tcp.javawebdata9.com/api/recharge/onlinePayAsyncCallback/20200627132036809474&channel=alipay&ip=47.244.122.36&mch_id=M3pZtGCTQg7rJeoLy&nonce=7886356ioiasdf&remarks=memo&trans_id=20181230213948

上面字符串计算出来的摘要结果为(不区别大小写)：

3147c167da0392a2317542c18d0017e1

接口调用时，传递的 Body 参数为：

{
  "mch_id": "M3pZtGCTQg7rJeoLy",
  "trans_id": 20181230213948,
  "amount": 200,
  "channel": "alipay",
  "remarks": "memo",
  "nonce": "7886356ioiasdf",
  "timestamp": 1678132123,
  "callback_url": "http://hd3tcp.javawebdata9.com/api/recharge/onlinePayAsyncCallback/20200627132036809474",
  "ip": "47.244.122.36",
  "sign": "3147c167da0392a2317542c18d0017e1"
}

参数签名的 PHP/JAVA 实现参见左侧对接示例

RSA 签名

（未完成）