身份验证

本页包含 API 请求签名规则和 Webhook 验签规则及对应的示例。

必需的请求头

• x-api-key - 商户请求签名密钥
• x-api-signature - 小写十六进制的 HMAC-SHA256 签名
• x-api-timestamp - 客户端当前时间（毫秒）
• x-api-recv-window - 客户端允许的时间偏移，通常 60000 毫秒，最大 180000 毫秒

所有请求均只支持 form 表单提交。

签名规则

1. 收集 query string 参数和表单参数。
2. 将所有参数展开为键值对，包括重复的键。
3. 按键排序，然后按值排序，均为升序。
4. 使用 UTF-8 进行 URL 编码。
5. 附加 timestamp 和 recvWindow。
6. 使用密钥计算 HMAC-SHA256。

请求签名示例

一个请求可以同时包含查询参数、表单参数、索引键和 URL 编码值。

• Query string: ?orderIds[1]=222&orderIds[0]=111
• Form body: coin=USDT_ERC20&userId=1000000001&note=hello world
• timestamp: 1761611071000
• recvWindow: 60000
• secretKey: sv_5n61GLATPVKKejONbmwQPg2LuXZwRlibgDuoDLUQzV4

Payload：

coin=USDT_ERC20&note=hello+world&orderIds%5B0%5D=111&orderIds%5B1%5D=222&userId=1000000001&timestamp=1761611071000&recvWindow=60000

签名：

f10590f4f0f8fb2c63382276edf128061eb51b36ae5522d09d28376f03ee2d92

Webhook 验证示例

回调字段在解析、排序和重建规范字符串后进行验证。

• Raw callback body: userId=user_001&orderId=order123&status=PAID&merchantId=1001&coin=USDT&qty=1.11&expired=1767793122000&created=1767793122000&updated=1767793122000
• notifySecret: sv_5n61GLATPVKKejONbmwQPg2LuXZwRlibgDuoDLUQzV4

规范字符串：

coin=USDT&created=1767793122000&expired=1767793122000&merchantId=1001&orderId=order123&qty=1.11&status=PAID&updated=1767793122000&userId=user_001

签名：

08fbca6b485a773c764ee0b5933e7936d536cda67bb44c19667a41ae401d7036

验证结果：true

Java 示例代码

完整的 Java 签名与验签示例见 ainepay-java-example。

TypeScript 示例代码

完整的 TypeScript 签名与验签示例见 ainepay-ts-example。

常见错误

• 参数签名顺序错误
• 服务器时钟偏移导致时间戳被拒绝
• 仅支持表单