最佳实践
幂等与重试、对账与补偿、安全建议，以及联调和上线检查清单。
本页是接入金融类 API 的通用做法。其中涉及 Stabo 行为的内容，以通用约定、Webhook和各产品指南为准。
幂等与重试
- 每个
POST请求都带Idempotency-Key。 - 网络超时或没收到响应时，用同一个
Idempotency-Key重试同一笔请求。Payment 转账接口例外：重复的 Key 会被拒绝，要改用referenceNo查询结果，见 Payment 幂等性。 - 不同业务请求用不同的
Idempotency-Key。可以用订单号派生，或用 UUID。 - 重试用指数退避。每次重试的间隔加倍，再加一点随机抖动，并设最大重试次数。
- 超出重试次数后，不要继续盲目重试。用查询接口确认结果，再决定是否人工处理。
- 收到 401 时，重新获取 Token 再重试。
- 收到 400 时，请求本身有问题。先按响应中的
message修正，不要原样重试。
对账与补偿
Webhook 是接收结果的主链路。查询接口是补偿和对账的手段。
- 以查询接口返回的状态为最终状态。Webhook 与查询结果不一致时，以查询结果为准。
- Webhook 可能重复，也可能乱序。按
Webhook-Event-Id去重。判断订单状态时看data.object.status，不要只看事件类型。 - 对长时间停留在非终态的订单，定时调用查询接口补查。
- 每日对账。按日期范围分页拉取列表，与本地订单逐笔比对
status和金额，把差异记录下来处理。 - 金额用字符串或 Decimal 保存和比较，不要用浮点数。比较时按币种精度处理。
- 记录每次请求的
traceId。对账出现差异、联系技术支持时，提供traceId。
安全建议
client_secret、Access Token 和 Webhook 密钥只保存在服务端。放在环境变量或密钥管理服务中，不要写进代码、前端、移动端或代码仓库。- 定期轮换密钥：在控制台新增一个密钥，切换到新密钥后删除旧密钥。怀疑泄露时，立即按同样方式更换，并删除旧密钥。
- Webhook 必须验签。用原始请求体计算，常数时间比较，并校验时间戳以防重放。详见 Webhook。
- Webhook 回调地址必须是 HTTPS。
- 在控制台为每个密钥配置 IP 白名单，只填写实际调用 Stabo 的服务器出口 IP。留空表示不限制来源 IP。出口 IP 变更时，同步更新白名单。
- 日志里不记录
client_secret、Access Token、Webhook 密钥和完整的账户信息。需要排查时只记录traceId、订单号等标识。 - 同一个 Token 在应用内缓存复用，不要每次请求都重新获取。
联调与上线检查清单
在测试环境联调
使用测试环境 Base URL https://api.test.stabofx.com 和测试环境凭证。
获取 Access Token，确认能拿到 access_token。
调用业务接口。以 Checkout 为例，创建 Payment Intent，拿到 checkoutUrl。
确认 Webhook 地址能收到通知，并用固定样本确认验签代码正确。
用查询接口查询订单，确认状态与 Webhook 一致。
上线前检查
- 生产环境的 Base URL、
client_id、client_secret和tenant_id已替换，且只保存在服务端。 - 生产服务器出口 IP 已加入白名单。
- Webhook URL 是公网可访问的 HTTPS 地址。
- Webhook 处理先返回 2xx，再异步处理业务，并在 30 秒内响应。
- Webhook 已验签：原始请求体、常数时间比较、时间戳容差。
- Webhook 按
Webhook-Event-Id去重，业务处理幂等。 - 所有
POST请求都带Idempotency-Key，重试时复用同一个 Key。Payment 转账超时后改用referenceNo查询结果，不重新提交。 - 金额用字符串或 Decimal，没有使用浮点数。
- 请求超时设为 30 秒，并实现指数退避重试。
- Token 已缓存，收到 401 时会重新获取。
- 已有定时补查任务和每日对账任务。
- 日志已脱敏，并记录了
traceId。