本页内容
API 密钥
创建 Payment 或 Payout API 密钥，了解其作用域与前缀，安全轮换凭证，并隔离测试与正式访问。
Paymos 为每个环境签发两类密钥，各自固定绑定一组操作。泄露的 Payment 凭证无法动用资金——作用域在每个请求上集中校验，因此无论请求打到哪个路由，Payment 密钥永远到不了 payout 端点。
密钥类型
| 类型 | 前缀 | 作用域 |
|---|---|---|
| Payment | pk_ |
创建账单、查询账单状态、管理收款通道并读取其充值 |
| Payout | rk_ |
创建转出、取消转出、查询余额 |
API secret 使用 sk_ 前缀。webhook 签名 secret 使用 whsec_。
环境
每个凭证都绑定一个环境，环境编码在前缀中：
| 环境 | 前缀修饰 | 示例 |
|---|---|---|
| 正式 | _live_ |
pk_live_…、rk_live_… |
| Sandbox | _test_ |
pk_test_…、rk_test_… |
配置完整的商户持有四个 API key ID（pk_live_…、pk_test_…、rk_live_…、rk_test_…）和两个 webhook secret（whsec_live_…、whsec_test_…）。
作用域说明
作用域的拆分是集中强制的，不取决于路由：访问级别在每个请求上由密钥类型推导，因此 Payment 密钥只能触达进钱侧的端点，Payout 密钥只能触达 payout 端点。
收款通道属于进钱这一侧。通道和充值的八个端点都要 Payment 密钥，对 Payout 密钥回 403 payment_key_required——和转出拒绝 Payment 密钥正好互为镜像。
最让人意外的是余额：GET /v1/balances 要的是 Payout 密钥。Payment 密钥待在店铺服务器上，随每次部署一起走，也最容易外泄，所以不让它看见你手上有多少。余额从你发起转出的同一处读取。
Payout 还有一道额外的闸门：Payout 凭证在添加 IP 白名单之前保持不可用——在控制台配置至少一个允许的 IP 之前，所有请求都会被拒绝。刚生成的 Payout 密钥自己无法动用资金。
Payout 密钥可以把资金转出你的 Paymos 余额——要像对待银行密码一样对待它。IP 白名单是密钥被盗与资金之间的那道墙，尽量收窄：只列出真正调用 payout API 的服务器 IP。
生命周期
| 状态 | 说明 |
|---|---|
| 已启用 | 凭证正常可用，接受请求 |
| 已吊销 | 终态。凭证被永久禁用，无法重新激活 |
安全最佳实践
- —绝不在客户端代码中暴露 API secret
- —通过控制台定期轮换 secret——过渡期内的宽限期会让旧 secret 继续有效
- —正式与 Sandbox 使用各自独立的凭证
- —为 Payout 凭证配置 IP 地址限制
- —API secret 只存放在环境变量或密钥管理器中
使用这些凭证的 HMAC-SHA256 签名方案见身份认证。