跳到主要内容

API 对接概述

Lampay API 专为服务端对服务端通信设计，使用 HMAC-SHA256 签名认证。当您的后端系统需要以编程方式与 Lampay 交互时（例如发起转账、查询钱包余额），使用此 API。

方面说明
认证方式HMAC-SHA256 签名
适用场景服务端对接、后端系统
凭证API 密钥 + 密钥对（长期）
传输HTTPS
会话无状态（每请求签名）

工作原理​

每个 API 请求必须包含四个自定义头，共同证明调用方拥有有效的 API 密钥并知道对应的密钥对。服务器在处理请求之前会验证这些头。

必需请求头

NameTypeRequiredDescription
X-Api-Keystringrequired您的 API 密钥标识符。格式：sk_live_xxx（生产环境）或 sk_test_xxx（沙箱环境）。
X-SignaturestringrequiredBase64 编码的 HMAC-SHA256 签名，基于规范消息（method、path、timestamp、nonce、body hash）计算。
X-Timestampstringrequired请求发起时的 Unix epoch 秒数（UTC）。必须与服务器时间相差不超过 60 秒。
X-Noncestringrequired唯一的请求标识符。推荐使用 UUID v4。每个 nonce 在时间戳窗口内只能使用一次。

快速示例​

以下是一个经过认证的 API 请求示例：

curl -X POST "https://api.lampay.app/api/v1/transfer/command/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_live_abc123def456" \
  -H "X-Signature: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=" \
  -H "X-Timestamp: 1709337600" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"sourceWalletId":"w_123","targetWalletId":"w_456","amount":"100.00","currency":"USD"}'

X-Signature 中的签名不是静态令牌 -- 它根据请求方法、路径、请求体、时间戳和 nonce 对每个请求重新计算。这意味着即使请求被截获，也无法被重放或篡改。

认证流程概览​

┌──────────────┐                              ┌──────────────┐
│  您的服务器   │                              │   Lampay   │
└──────┬───────┘                              └──────┬───────┘
       │                                             │
       │  1. 构建规范消息                              │
       │     (method + path + timestamp +             │
       │      nonce + SHA256(body))                   │
       │                                             │
       │  2. 使用 HMAC-SHA256(secret) 签名             │
       │                                             │
       │  3. 发送带 4 个认证头的请求                    │
       │ ──────────────────────────────────────────> │
       │                                             │
       │        4. 服务器验证：                        │
       │           - 密钥是否存在且有效                 │
       │           - 时间戳是否在 60 秒内               │
       │           - Nonce 是否唯一                    │
       │           - 签名是否匹配                      │
       │           - IP 是否允许（如已配置）             │
       │           - 权限范围是否许可                   │
       │                                             │
       │  <── 5. 响应（成功或错误） ─────────────────── │
       └─────────────────────────────────────────────┘

后续步骤​

  • HMAC 认证 -- 签名计算的分步指南，包含 Bash 和 Node.js 的完整代码示例。
  • API 参考与错误码 -- 错误码、API 密钥管理和技术规范。
  • 错误处理 -- 响应信封格式和完整的错误码目录。
  • 分页 -- 如何对大结果集进行分页。