签名请求指南

使用需要进行身份验证的币趣支付 API 均需要对请求数据进行严格的签名。本指南将为您拆解具体的底层网络加密与签名过程。

TIP

如果您使用的是各语言环境的 币趣支付 SDK，则无需查阅此章节。SDK 已经在底层封装了所有的签名逻辑和网络请求头配置，您只需正确提供密钥或证书即可。

当您由于系统受限或特殊原因，必须使用原生的 HTTP 请求库与币趣 API 交互时，请遵循本页面为您选择的方案完成签名。

1. 签名数据的公共规则 (构建签名串)

无论您使用的是哪种加密方式，算法所需要的 “待签名字符串” 的拼接逻辑都是统一且固定的。

您需要将：请求的完整 URL 与 请求的数据正文(Body) 直接拼接在一起。这是保证数据完整性且不被篡改的核心所在。

极其重要：数据正文的严格一致性

参与拼接的 请求的数据正文(Body) 必须与您实际发送在 HTTP 请求中的原始文本体 完全、一字不差地一致（包括空格、换行、字段顺序）。这是因为我们的网关是通过直接拦截并提取请求的原始字节文本流进行验签的。如果您在计算签名后，又通过某些 HTTP 库格式化了 JSON（例如改变了字段顺序、去除了换行或增删了多余的空格），将必然导致两端的待签名字符串不一致，从而引发验签失败！

带有 Body 的 POST/PUT 请求范例：

text

待签名字符串 = https://openapi.basicex.com/v2/invoices{"t": "123"}

没有 Body 的 GET/DELETE 请求范例：仅由请求的 URL 组成，不要追加任何空字符或换行。
text
```
待签名字符串 = https://openapi.basicex.com/v2/invoices/40620230828091249764130683289837
```

2. 选择您的签名算法

根据您在商户平台的配置，您可以采取 API Key (HMAC) 或是 API 证书 (RSA) 中的一种生成您的 X-Signature。

方案 A：使用 API Key 签名 (HMAC-SHA512)

这是更为简便轻巧的接入方式。在商户平台您将获得一对 (ApiKey, SecretKey)。

计算签名：使用大多数编程语言标准库中的 HMAC 模块。以您的 Secret Key 作为密钥，对上述 待签名字符串 计算 HMAC-SHA512 的哈希值。
编码输出：将计算所得到的二进制结果编码为 16进制字符串 (Hex String)。并转换为全小写方式。
设置请求头：将 ApiKey 置于请求头 X-Api-Key。将上述16进制字符串签名置于请求头 X-Signature。
http
```
X-Api-Key: a48f12c...
X-Signature: c81a9f0322ba2e89b... (Hex 编码值)
```

方案 B：使用商户 API 证书签名 (RSA)

这是更为硬核严格的鉴权方式。商户平台颁发的 API 证书中包含一对公私钥，私钥以 商户号.key 文件形式或在 config.json 中保存，请极度保密。

计算签名：提取出您的私钥，对 待签名字符串 执行 SHA-256 with RSA 的非对称签名。

编码输出：由于 RSA 签名产生的字节流并非可打印字符，必须将结果进行 Base64 编码。

bash

# CLI 测试签名案例
$ echo -n -e \
 "https://openapi.basicex.com/v2/invoices/40620230822134552202883210445009" \
 | openssl dgst -sha256 -sign 813161626275841.key \
 | openssl base64 -A

设置请求头：因为需要通过证书来证明身份，还需要提取出公钥证书 (.cer、.crt 或 .pem 里的以 -----BEGIN CERTIFICATE----- 开头的部分)。
- 请注意： 受限于 HTTP Header 规范对换行符的限制，您需要把证书文件内容中的所有真正换行符去除变成一行置入 X-Identity 中！
- 此后，将 Base64 编码的签名串置入 X-Signature 中。
http
```
X-Identity: -----BEGIN CERTIFICATE-----MIIFiTCCA3Gg... (去除了换行符的单行超长字符串) ...DaxGmic/aWMjxLAVb7280RW6g=-----END CERTIFICATE-----
X-Signature: G8iDi8OsMVC5G7mOmwQ+tIrU7UrcsPgb... (Base64 编码值)
```

3. Webhook 的平台级验签

您的后端被动接收到币趣支付系统的推送时，也需要验证数据的可靠性。

关于币趣通知的验签说明由于十分重要且与主动 API 请求流程相反，我们抽离到了专门的 Webhook 指南单页中。 👉 如果您的服务需要响应异步资金通知，请强烈建议查阅： Webhook 接收与证书验签处理原则

如果您请求遭遇了 401 Unauthorized 错误状态码返回，请重点检查上述待签名体或者 HTTP Header 的编码转换逻辑。

签名请求指南 ​

1. 签名数据的公共规则 (构建签名串) ​

2. 选择您的签名算法 ​

方案 A：使用 API Key 签名 (HMAC-SHA512) ​