快速开始¶

对接前置¶

向平台申请开通开放 API，并获取 API 密钥（仅下发一次明文，请妥善保管）。
确认平台已告知你的 收银台 Base URL（文档中的 {BASE_URL}）。
准备可接收 HTTPS POST 的 Webhook 地址（推荐），用于接收支付结果；也可仅用查询接口轮询。
若需客户支付后回到你的站点，准备一个 HTTPS 回跳地址（return_url）。

密钥安全

API 密钥仅用于服务端调用，禁止写入前端、App、公开仓库或客户端配置。

推荐对接流程¶

1. POST /api/v1/open/charges  创建收款单
2. 将返回的 payment_url 展示给客户完成支付
3. 同时：
   - 接收 Webhook（PAID / FAILED …），或
   - 轮询 GET /api/v1/open/charges/{orderId}
4. （可选）客户浏览器经 return_url 回到你的站点
5. （可选）支付失败需换通道再试：
   先 GET /api/v1/open/charges/{orderId}/retry-advice 判断是否值得重试，
   再用 return_url 的 pay_order_id 作为 retry_of 创建一单 → 见 失败后重新建单
6. （可选）支付失败需人工指定通道：
   GET /api/v1/open/payment-gateways?retry_of=… 查看可选通道，
   再 POST /charges 同时传 retry_of + gateway_id + 新的 merchant_order_id
   → 见 获取可用支付通道 / 失败后重新建单

幂等建议¶

创建收款单时建议携带请求头 Idempotency-Key（如 UUID）。同一商户下相同幂等键的重复请求，将返回首次建单结果，避免网络重试导致重复下单。

支付失败后的业务重试请使用新的 merchant_order_id + retry_of（见失败后重新建单），不要复用首次建单的幂等键。