身份验证与 IP 白名单

检查顺序

每个请求按以下顺序检查，任一项不通过即返回错误：

  1. 签名：api_identity 必须是状态为正常的凭证，且 sign 正确。不通过时返回 invalid_signature（HTTP 401）。
  2. 时间戳：timestamp 必填，格式 yyyy-MM-dd HH:mm:ss（UTC+8），与 ST Pay 服务器时间相差不得超过 5 分钟。缺少时返回 missing_parameter，格式不符返回 invalid_parameter，相差超过 5 分钟返回 timestamp_expired（HTTP 400）。签名通过后才检查时间戳，因此 timestamp 被篡改时返回 invalid_signature。
  3. 来源 IP：必须在该商户的 API 白名单内。白名单为空时全部拒绝。不通过时返回 ip_not_allowed（HTTP 403）。
  4. 商户状态（仅建单时检查）：商户被停用时不能建单，返回 merchant_disabled（HTTP 403）。停用期间仍可查单。

保管密钥

  • 密钥只能存放在您的服务器端，不要放入网页、App 或任何会分发给终端用户的程序中。
  • 密钥泄露或丢失时，请立即联系 ST Pay 创建新凭证并停用旧凭证。

更换密钥

同一商户可以同时拥有多组状态为正常的凭证，每组都可用于调用 API。Callback 统一使用最新创建且状态为正常的那组密钥签名，因此建议按以下顺序更换密钥：

  1. 先让您的 Callback 验签程序能同时接受两个密钥（新密钥要在第 2 步之后才能拿到，可先预留好配置位置）。
  2. 请 ST Pay 创建新凭证，并将新密钥加入 Callback 验签。新凭证创建后，Callback 会立即改用新密钥签名；新密钥加入验签之前收到的 Callback 会验签失败，这些订单请以查单确认结果，或请 ST Pay 重发。
  3. 调用 API 时改用新的 api_identity 与密钥。
  4. 确认已没有请求使用旧凭证后，请 ST Pay 停用旧凭证，并从 Callback 验签中移除旧密钥。