身份认证

StablePay API 使用 API Key 进行身份验证。所有 API 请求都必须在 HTTP Header 中包含有效的 API Key。

API Key 类型

StablePay 提供两种类型的 API 密钥：

类型前缀用途环境
测试密钥sk_test_用于开发和测试环境测试环境（Sandbox）
生产密钥sk_live_用于生产环境的真实交易生产环境

重要说明：

  • 测试密钥和生产密钥使用不同的 API 端点
  • 测试密钥产生的交易不会在区块链上真实执行
  • 生产密钥产生的交易会产生真实的资金转移

获取 API Key

步骤

  1. 登录 StablePay 商户后台
  2. 进入 开发者设置 > API 密钥
  3. 点击 创建新密钥
  4. 为密钥设置以下信息：
    • 名称：便于识别的密钥名称
    • 类型：测试密钥或生产密钥
    • 权限范围：选择适当的权限级别
    • IP 白名单（可选）：限制只能从特定 IP 访问
  5. 点击 创建 并保存密钥

安全警告

API 密钥仅在创建时显示一次！ 请立即保存到安全的地方。如果丢失，需要重新生成新密钥。

认证方式

HTTP Header 认证（推荐）

在每个 API 请求的 HTTP Header 中包含 API Key：
Authorization: Bearer YOUR_API_KEY
**完整请求示例：**
curl -X GET https://api.stablepay.co/v1/payment/sessions/sess_123 \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

权限范围

权限说明可执行操作
read只读权限查询支付会话、交易记录、账户信息等
write写入权限创建支付会话、发起退款、更新商户信息
admin管理权限删除资源、配置 Webhook、管理 API 密钥

认证错误

401 Unauthorized

原因：

  • API Key 无效或格式错误
  • API Key 已过期
  • API Key 已被删除或撤销
  • 未提供 API Key
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}

403 Forbidden

原因：

  • API Key 缺少执行该操作所需的权限
  • API Key 受 IP 白名单限制
  • 账户被暂停或受限

最佳实践

  1. 使用环境变量 - 不要将 API Key 硬编码在代码中
  2. 分离测试和生产环境 - 为不同环境使用不同的密钥
  3. 定期轮换密钥 - 建议每 3-6 个月更换一次
  4. 使用密钥管理服务 - 推荐 AWS Secrets Manager 或 HashiCorp Vault
  5. 服务器端认证 - 永远不要在客户端暴露 API Key
// ✅ Correct: Use environment variables
const client = new StablePay({
  apiKey: process.env.STABLEPAY_API_KEY
});
最后更新 / Last Updated: