支付
1. 概述
本文档旨在为应用程序（APP）的研发团队提供集成 SUD 支付模块（SUD Payment）的技术指南。文档详细说明了 SUD 运营 SDK（SUD OP SDK）与 APP 之间的客户端交互逻辑，以及 SUD 后端与 APP 后端之间严密的服务端订单状态同步与异常退款流程。
2. 参与者角色定义
2.1 客户端侧
- APP: 应用程序客户端。负责向用户展示收银台，完成支付密码/生物认证，并实际对接第三方支付网关完成资金交割。
- SUD OP (SUD SDK): SUD 运营客户端 SDK。作为发起方，接收内部游戏端请求后向 APP 发起支付，并接收前端结果。
2.2 服务端侧
- SUD OP SVR: SUD 运营后端服务器。负责维护全局订单状态，与 APP 服务端进行资金状态确认，并在内部驱动游戏端发货或关单。
- APP SVR: 应用程序后端服务器。实际的资金处理枢纽，负责对前端发起的收银台请求进行安全鉴权，主动推送支付回调、响应 SUD 的主动查询，并处理兜底的退款请求。
3. 核心交互流程
本时序图展示了 APP 侧需要参与的完整生命周期，包括：订单拉起、服务端双端状态同步（重点），以及异常情况下的退款交互。
3.1 关键交互阶段说明
- 支付拉起与事前安全鉴权阶段 (核心防御)：
SUD OP接收到游戏端的支付请求后，在SUD OP SVR创建订单，并获取一个带有强签名的防篡改参数包 (pay_payload)。随后唤起APP支付环节。APP在真正对接底层第三方网关扣款前，必须将此参数包透传给APP SVR进行合法性校验。校验通过后才允许发生实际资金交割。最终APP返回给SUD OP的仅为前端结果 (Frontend Only)。 - 前端结果同步与触发查询阶段：
SUD OP在收到APP的前端结果后，会立即向SUD OP SVR同步该结果。此动作将立即唤醒SUD OP SVR，触发其向APP SVR发起异步的支付结果核实动作 (Initiate async payment verification)。 - 服务端双重同步与内部驱动阶段：为了保证资金与资产的绝对安全，
APP SVR需要与SUD OP SVR建立双重保障（回调+轮询）：- 主动查询机制 (
Active Order Polling)：包含两个维度的触发条件。其一为前端结果触发的即时查询；其二为订单创建后触发的超时定时轮询（兜底防掉单）。 - 状态获取与内部驱动 (
Internal Action)：一旦SUD OP SVR获取到最终资金状态 (PAID或CLOSED)，即刻终止查询循环。 - 金额核对与拦截 (
Validation)：SUD OP SVR在获取到APP SVR返回的支付成功状态时，必须提取其实际支付金额与币种，并与预下单时的原始金额进行严格比对。若发现不一致（如遭恶意篡改），即使 APP 侧实际已扣款，SUD OP SVR也将强制阻断发货，立刻向APP SVR发起风控兜底退款，并向游戏端转入关单流程，确保资金不被异常吞没。
- 主动查询机制 (
- 异常退款兜底阶段：如果 SUD 内部流转出现异常（例如内部驱动游戏发货失败），
SUD OP SVR会向APP SVR发起退款请求，APP SVR需受理并原路退回用户资金。
4. APP 侧核心状态机流转
虽然全局订单状态由 SUD 维护，但 APP SVR 作为真实的资金处理枢纽，必须准确理解并传递以下核心状态。
4.1 APP 侧状态字典与职责映射
| 状态枚举 | 状态含义 | APP SVR 侧核心职责与触发时机 |
|---|---|---|
PAYING | 用户支付中 | 当 SUD 主动查询时，若用户仍在收银台操作，返回此状态。 |
PAID | 支付成功 | 资金实际扣除后，APP SVR 必须立刻通过主动回调（Webhook）推送此状态给 SUD，或在查询接口中明确返回。 |
CLOSED | 支付关闭/取消 (终态) | 若用户主动取消支付、超时未付或扣款明确失败，APP SVR 必须将此状态反馈给 SUD，以便 SUD 释放上游业务资源。 |
REFUNDING | 触发兜底退款 | 当 SUD 内部发生发货异常时，会携带此状态发起退款请求，APP SVR 需受理并准备退回资金。 |
REFUNDED | 退款完成 (终态) | APP SVR 成功完成资金原路退回。 |
REFUND_FAIL | 退款失败 | APP SVR 无法完成退款（如账户注销等），需通知 SUD 进行人工/财务介入。 |
5. APP API 对接清单
为了实现上述流程，应用程序后端服务器 (APP SVR) 必须提供以下三个维度的能力与接口：
支付请求安全校验 API (Validate Payload API)：
- 职责 (内部调用)：响应 APP 客户端在拉起底层收银台前发起的鉴权请求。
- 要求：
APP SVR必须解密并验证pay_payload中的签名是否合法，且确由SUD OP SVR真实签发。一旦验签失败，一律阻断支付流程，防止恶意客户端绕过 SUD 伪造支付请求。
支付结果回调 API (Webhook/Callback)：
- 职责：在用户完成扣款或支付关闭时，主动将结果推送给 SUD (对应：服务端双端状态同步阶段)。请求报文中必须包含实际扣款的明确金额与币种。
订单状态查询 API (Query API)：
- 职责：响应 SUD 发起的 Active Order Polling 轮询请求 (对应：主动查询机制)。响应报文中必须包含实际扣款的明确金额与币种。
- 强制规范要求：
APP SVR必须准确返回PAID（已支付）、PAYING（支付中）或CLOSED（已关闭/已取消）。尤其是当用户在 APP 收银台主动取消支付，或底层扣款明确失败时，APP SVR 必须返回CLOSED，而不能持续返回PAYING。只有明确接收到CLOSED状态，SUD OP SVR才能向游戏服务端下发“关单指令”以释放 Game 订单。
退款受理 API (Refund API)：
- 职责：响应
SUD OP SVR因游戏端发货异常或**金额校验不通过（风控拦截）**而发起的兜底退款请求 (对应：异常退款兜底阶段)。 - 要求：需支持按订单号进行全额退款操作，并返回退款受理的明确结果。
- 职责：响应