Skip to content

支付简介 ​

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):包含两个维度的触发条件。其一为前端结果触发的即时查询;其二为订单创建后触发的超时定时轮询(兜底防掉单),轮询间隔与终止条件见 pay.orderQuery 的「轮询策略」。
    • 状态获取与内部驱动 (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 主动查询时,若用户仍在收银台操作,返回此状态。该状态通过 pay.orderQuery 返回,无需通过 pay.notify 上报。
PAID支付成功资金实际扣除后,APP SVR 必须立刻通过主动回调(Webhook)推送此状态给 SUD,或在查询接口中明确返回。
CLOSED支付关闭/取消 (终态)若用户主动取消支付、超时未付或扣款明确失败,APP SVR 必须将此状态反馈给 SUD,以便 SUD 释放上游业务资源。
REFUNDING退款处理中(非上报状态)APP SVR 受理 pay.refund 后的处理中状态。SUD 通过 pay.refundQuery 查询获知,无需通过 pay.refundNotify 上报;APP SVR 受理后应准备退回资金。
REFUNDED退款完成 (终态)APP SVR 成功完成资金原路退回。
REFUND_FAIL退款失败 (终态)APP SVR 无法完成退款(如账户注销等)。属于终态,不再通过 pay.refundNotify 流转后续状态,需人工/财务线下介入处理。

5. APP API 对接清单 ​

为了实现上述流程,应用程序后端服务器 (APP SVR) 必须提供以下三个维度的能力与接口:

  1. 支付请求安全校验 API (Validate Payload API):

    • 职责 (内部调用):响应 APP 客户端在拉起底层收银台前发起的鉴权请求。
    • 要求:APP SVR 必须解密并验证 pay_payload 中的签名是否合法,且确由 SUD OP SVR 真实签发。一旦验签失败,一律阻断支付流程,防止恶意客户端绕过 SUD 伪造支付请求。
  2. 支付结果回调 API (Webhook/Callback):

    • 职责:在用户完成扣款或支付关闭时,主动将结果推送给 SUD (对应:服务端双端状态同步阶段)。请求报文中必须包含实际扣款的明确金额与币种。
  3. 订单状态查询 API (Query API):

    • 职责:响应 SUD 发起的 Active Order Polling 轮询请求 (对应:主动查询机制)。响应报文中必须包含实际扣款的明确金额与币种。
    • 强制规范要求:APP SVR 必须准确返回 PAID(已支付)、PAYING(支付中)或 CLOSED(已关闭/已取消)。尤其是当用户在 APP 收银台主动取消支付,或底层扣款明确失败时,APP SVR 必须返回 CLOSED,而不能持续返回 PAYING。只有明确接收到 CLOSED 状态,SUD OP SVR 才能向游戏服务端下发“关单指令”以释放 Game 订单。
  4. 退款受理 API (Refund API):

    • 职责:响应 SUD OP SVR 因游戏端发货异常或**金额校验不通过(风控拦截)**而发起的兜底退款请求 (对应:异常退款兜底阶段)。
    • 要求:需支持按订单号进行全额退款操作,并返回退款受理的明确结果。同一 sud_refund_no 的重复请求必须返回同一 refund_id,不得生成第二笔退款,详见 pay.refund 的「幂等说明」。
  5. 回调地址配置请查看:支付进件