虚拟支付配置 - 道具直购
适用范围：道具直购（Direct IAP） 本文仅覆盖"玩家通过现金直接购买指定道具，由 Game SVR 负责发放该道具"这一支付场景。 另一类常见场景"虚拟币充值"（玩家先充值游戏内通用代币、再消耗代币购买道具）将由独立文档说明，两类场景在订单模型、发货时机与对账方式上均存在差异，请勿混用本文规范。
1. 概述 (Overview)
本文档旨在为游戏开发者（CP，Content Provider）提供集成 SUD 道具直购能力的核心技术指南。文档详细说明了游戏客户端如何通过 SUD SDK 针对单一道具发起支付调用，以及游戏服务端如何安全、可靠地轮询发货状态并接收 SUD 服务端下发的发货/关单回调通知。
2. 参与者 (Participants) 角色定义
2.1 客户端侧 (Client-Side)
- Player: 游戏玩家，发起购买操作的最终用户。
- SUD OP (SUD SDK): SUD 运营客户端 SDK。作为支付中间件，接收 Game 的指令并处理底层的支付界面唤起逻辑。
- Game: 游戏客户端。负责向游戏服务端申请 Game 预订单，并调用 SUD SDK 拉起支付界面。
2.2 服务端侧 (Server-Side)
- Game SVR: 游戏后端服务器。负责生成游戏内部订单（Game Order）、提供客户端轮询接口，并接收 SUD 官方下发的异步回调通知以执行道具发放或订单关闭。
- SUD OP SVR: SUD 运营后端服务器。支付中台核心，负责确认最终真实的资金状态，并在确认后向 Game SVR 下发安全的操作指令。
3. 核心交互流程 (Interaction Sequence)
3.1 关键步骤说明 (Key Steps Explanation)
- Game 订单预生成阶段：当玩家点击购买指定商品时，
Game必须先向自己的Game SVR请求生成一个内部业务订单（Game Order，需包含具体的product_id），随后携带此订单参数调用 SUD SDK 发起支付。Game SVR在返回订单参数的同时需计算支付原串与两个签名（支付态签名paySig、用户态签名signature），构造规则与算法见支付签名规范。 - 支付处理与前端结果同步阶段：SUD 系统会在内部处理所有复杂的支付流转。
SUD OP会将前端结果同步给服务端，以此触发SUD OP SVR去底层核实真实资金。- ⚠️ 严格警告：游戏客户端绝对不能依靠返回的前端
SUCCESS直接向玩家发货，这会导致极高的被单机破解伪造支付的风险。一切发货动作必须依赖服务端的指令。
- ⚠️ 严格警告：游戏客户端绝对不能依靠返回的前端
- 客户端轮询机制与 UI 响应阶段：
Game收到前端结果后，开始向自己的Game SVR轮询道具是否已到账。若Game SVR返回成功或失败，客户端跳出轮询并更新 UI 提示玩家；若返回处理中（Pending），则在预设的间隔时间后，发起下一次状态查询请求，直至触发成功、失败或超时终态。 - 核心 Webhook 与状态决断阶段：
- 支付成功分支 (
Result == PAID)：SUD OP SVR确认资金入账，向Game SVR发送发货通知。Game SVR必须进行验签，校验通过后发放资产。若Game SVR明确返回业务失败（如账号异常），或SUD OP SVR重试下发 Webhook 达到最大次数后仍超时，SUD OP SVR将自动介入执行退款兜底 (REFUNDING)，防止误退款或掉单。 - 支付关闭分支 (
Result == CLOSED)：如果底层查到玩家未付款或主动取消，SUD OP SVR会下发关单通知。Game SVR收到后关闭该 Game 订单。
- 支付成功分支 (
4. Game 订单状态机流转 (State Machine for Game)
对于 Game 而言，无需关心底层的重试与网络对账逻辑，仅需在业务库中维护以下简化的核心状态机：
| 状态枚举 | 状态含义 | Game 侧动作指导 |
|---|---|---|
PAID | 资金已确认，SUD 开始推送发货 Webhook | Game SVR 准备接收回调并进行验签、发货处理。 |
CLOSED | 已关闭 (最终态) | 触发条件：玩家取消、扣款失败，或实际支付金额与原始订单不符（SUD 风控拦截）。Game SVR 收到关单 Webhook，终止订单并释放相关业务资源。 |
DELIVERED | 已发货 (最终态) | Game SVR 成功处理 Webhook 发货，订单正常完结。 |
REFUNDING | 退款中 (异常兜底) | 因 Game SVR 发货失败触发。Game 侧可将其内部订单标记为"发货异常/已退款"。 |
5. 游戏服务端 (Game SVR) 核心开发规范
为了确保玩家的资产安全与系统的稳定性，Game 后端研发团队在实现 SUD 异步回调接口 (Async Webhook) 时，必须严格遵循以下三大开发安全原则：
- 强签名校验 (Signature Verification)： SUD 在发送回调请求时，会在 HTTP Header 中附带签名字符串，回调报文本身也经过加密。
Game SVR必须使用平台证书中的公钥完成验签、并解密报文后再处理业务。验签失败的请求必须直接拒绝（返回 FAILED），以防止外部恶意伪造发货请求。具体的算法、请求头字段与错误码见服务端 API 签名加密。 - 防重发与接口幂等 (Idempotency)： 受公网网络波动影响，SUD 可能会对同一个订单发起多次 Webhook 回调重试。
Game SVR必须通过数据库的唯一约束（如订单号）实现幂等性处理。同一个订单仅允许成功发货或关单一次。针对重复的回调请求，只要资产已发或订单已关，也必须向 SUD 返回 SUCCESS。 - 订单金额与商品信息的强校验 (Validation)： 在发放高价值资产前，
Game SVR务必再次核对 SUD 回调报文中的product_id(商品 ID)、"实际支付金额"与"币种"，并与本地 Game 订单当时拉起时所请求的商品价值进行严格的三向比对。只有当商品一致且支付金额满足该商品的售价时才允许发货，严防"以小博大"或"低价买高价商品"的黑灰产篡改行为。
6. 运营后台 - 道具配置
在客户端调用 requestSUDPayment 之前，需要先在 SUD 运营后台为每一种可售商品创建道具元数据（product_id、道具名称、单价、币种等）。客户端发起支付时所携带的 product_id 必须与此处配置一致，Game SVR 在收到发货 Webhook 时也将使用该 product_id 完成第 5 节所述的三向比对校验。换言之，道具配置是接入支付能力的运营前置步骤，配置完成后才能进入第 3 节的核心交互流程。
6.1 进入道具配置页
在”虚拟支付-支付产品管理-道具配置”中，基于道具直购能力，配置特定的道具信息。 
6.2 添加道具
在”虚拟支付-支付产品管理-道具配置-添加道具”后设置道具的相关信息 