充值回调（Webhook）

本文包含两类通知：

• 合作方 -> 平台：合作方在「充值成功」时通知平台入账
• 平台 -> 合作方：平台在「充值成功」后回推合作方（如你方提供 notify_url）

合作方 -> 平台：充值成功通知

回调 IP 白名单校验（强制）

平台会验证回调请求来源 IP 是否在约定白名单中；若不在白名单，将拒绝请求。

请求

POST <API_URL>（联系平台获取）

请求头

Header	必填	说明
X-API-Key	是	平台分配的密钥，用于验证请求来源
Content-Type	是	application/json

请求体（JSON）

{
  "account": "abc123",
  "recharge_no": "RC202501010001",
  "amount": "100.00",
  "notify_url": "https://example.com/notify"
}

字段名	类型	必填	说明
account	string	是	用户充值账户
recharge_no	string	是	你方充值流水号，必须唯一（幂等键）
amount	string	是	充值金额，单位元
notify_url	string	否	平台向你方回推充值结果的地址（见下文）

签名校验（推荐）

平台仅校验 X-API-Key，并强制校验来源 IP 白名单。

幂等性

• 平台以 recharge_no 作为幂等键进行入账
• 合作方必须保证 recharge_no 全局唯一且稳定
• 合作方可安全重试同一 recharge_no 的通知，不会导致重复入账

返回结果

成功返回

{
  "code": 200,
  "message": "success"
}

失败返回

{
  "code": 400,
  "message": "invalid request"
}

成功/失败以 HTTP 状态码为准：HTTP 200 视为成功；非 200 视为失败并需要重试。响应体仅用于排障参考。

通知失败后的重试机制（合作方侧）

以下情况需重试：

• 平台返回 HTTP 非 200
• 网络超时 / 连接失败

推荐指数退避：5s -> 15s -> 60s，并持续重试到达到你方的最大重试窗口为止。

充值订单查询接口（配套）

合作方通知成功后，如需查询平台侧处理结果，可调用该查询接口。

请求

GET <API_URL>?account=xxx&amount=100.00&recharge_no=123456（联系平台获取）

请求头

Header	必填	说明
X-API-Key	是	与充值通知相同，用于校验来源

返回示例

{
  "code": 200,
  "data": {
    "status": 2,
    "fail_reason": "金额不符"
  }
}

字段名	说明
status	1=已完成；2=处理中或失败（失败原因见 fail_reason）
fail_reason	可能为：订单超时、金额不符、重复充值

平台 -> 合作方：充值成功回推（可选）

当充值成功后，平台会向合作方提供的回调地址推送通知；仅在 status = 1 时触发。

请求

POST <notify_url>

请求头

Header	必填	说明
X-API-Key	是	与合作方通知平台时相同的密钥
Content-Type	是	application/json

请求体（JSON）

{
  "recharge_no": "RC202501010001",
  "status": 1
}

响应要求

• 以 HTTP 状态码为准：合作方返回 HTTP 200 视为成功，不再重试
• 返回非 200 或无响应：平台会按策略自动重试