认证与签名 - ipayxx API 文档

API 密钥认证

Phase 2 功能

API 密钥管理控制台将在 Phase 2 上线。当前阶段请联系技术支持获取测试密钥。

所有 API 请求需要在 HTTP Header 中携带有效的 API Key 进行身份认证：

Authorization: Bearer your_api_key

密钥类型

类型	前缀	用途
测试密钥	`sk_test_`	开发与测试环境
生产密钥	`sk_live_`	生产环境

请求签名

为确保请求安全性和完整性，所有涉及资金操作的 API 请求需要附加请求签名。签名使用 HMAC-SHA256 算法。

签名流程

将请求参数按字母序排列
拼接为 key=value 格式的查询字符串
在末尾追加 &secret=your_api_secret
对完整字符串进行 HMAC-SHA256 哈希运算
将哈希结果放入请求头 X-Signature

请求头示例

POST /v1/orders HTTP/1.1
Host: api.ipayxx.cn
Authorization: Bearer sk_test_xxxxxxxxxxxx
Content-Type: application/json
X-Timestamp: 1709884800
X-Nonce: a1b2c3d4e5
X-Signature: 8f14e45fceea167a5a36dedd4bea2543

签名计算示例

// Node.js 签名示例
const crypto = require('crypto');

function signRequest(params, secret) {
  // 1. 按字母序排列参数
  const sortedKeys = Object.keys(params).sort();

  // 2. 拼接查询字符串
  const queryString = sortedKeys
    .map(key => `${key}=${params[key]}`)
    .join('&');

  // 3. 追加 secret
  const signString = `${queryString}&secret=${secret}`;

  // 4. HMAC-SHA256 哈希
  return crypto
    .createHmac('sha256', secret)
    .update(signString)
    .digest('hex');
}

安全须知

重要提醒

请勿在客户端代码中暴露 API Secret。所有 API 调用应从您的服务端发起。

API Secret 仅在创建时显示一次，请妥善保管
如密钥泄露，请立即在控制台重新生成
所有请求必须使用 HTTPS
建议为不同环境使用不同的密钥对
请求签名包含时间戳，有效期为 5 分钟