Payment Overview
1. Overview
This document is intended to provide the application (APP) development team with a technical guide for integrating the SUD Payment module (SUD Payment). It details the client-side interaction logic between the SUD OP SDK (SUD OP SDK) and the APP, as well as the strict server-side order status synchronization and exception refund flow between the SUD backend and the APP backend.
Onboarding Process: Payment Onboarding
2. Participant Role Definitions
2.1 Client Side
- APP: The application client. Responsible for presenting the checkout page to the user, completing payment password / biometric authentication, and actually integrating with the third-party payment gateway to complete the funds settlement.
- SUD OP (SUD SDK): The SUD operations client SDK. As the initiator, it receives requests from the internal game side and initiates payment to the APP, and receives the front-end result.
2.2 Server Side
- SUD OP SVR: The SUD operations backend server. Responsible for maintaining the global order status, confirming the funds status with the APP server, and internally driving game-side delivery or order closure.
- APP SVR: The application backend server. The actual funds processing hub, responsible for security authentication of checkout requests initiated by the front end, actively pushing payment callbacks, responding to SUD's active queries, and handling fallback refund requests.
3. Core Interaction Flow
This sequence diagram shows the complete lifecycle in which the APP side needs to participate, including: order invocation, dual-server status synchronization (key focus), and refund interaction under exception conditions.
3.1 Key Interaction Phase Descriptions
- Payment invocation and pre-transaction security authentication phase (core defense): After
SUD OPreceives the payment request from the game side, it creates an order inSUD OP SVRand obtains a tamper-proof parameter package (pay_payload) with a strong signature. It then invokes theAPPpayment step. BeforeAPPactually integrates with the underlying third-party gateway to charge, it must pass this parameter package through toAPP SVRfor legality validation. Only after validation passes is the actual funds settlement allowed to occur. WhatAPPfinally returns toSUD OPis only the front-end result (Frontend Only). - Front-end result synchronization and query trigger phase: After
SUD OPreceives the front-end result fromAPP, it immediately synchronizes the result toSUD OP SVR. This action immediately wakes upSUD OP SVR, triggering it to initiate an asynchronous payment result verification (Initiate async payment verification) withAPP SVR. - Server-side dual synchronization and internal driving phase: To ensure the absolute security of funds and assets,
APP SVRneeds to establish dual safeguards withSUD OP SVR(callback + polling):- Active query mechanism (
Active Order Polling): Includes trigger conditions across two dimensions. One is the immediate query triggered by the front-end result; the other is the timeout scheduled polling triggered after order creation (a fallback to prevent lost orders). Polling intervals and stop conditions are defined in the "Polling Policy" section of pay.orderQuery. - Status retrieval and internal driving (
Internal Action): OnceSUD OP SVRobtains the final funds status (PAIDorCLOSED), it immediately terminates the query loop. - Amount reconciliation and interception (
Validation): WhenSUD OP SVRobtains the payment-success status returned byAPP SVR, it must extract the actual payment amount and currency and strictly compare them against the original amount at pre-order time. If a discrepancy is found (e.g., malicious tampering), even if the APP side has actually charged the payment,SUD OP SVRwill forcibly block delivery, immediately initiate a risk-control fallback refund toAPP SVR, and transfer the game side into the order-closure flow, ensuring funds are not abnormally swallowed.
- Active query mechanism (
- Exception refund fallback phase: If an exception occurs in SUD's internal flow (for example, internally driving game delivery fails),
SUD OP SVRwill initiate a refund request toAPP SVR, andAPP SVRmust accept it and return the user's funds via the original route.
4. APP-Side Core State Machine Transitions
Although the global order status is maintained by SUD, APP SVR, as the actual funds processing hub, must accurately understand and convey the following core states.
4.1 APP-Side State Dictionary and Responsibility Mapping
| State Enum | State Meaning | APP SVR-Side Core Responsibilities and Trigger Timing |
|---|---|---|
PAYING | User is paying | When SUD actively queries, if the user is still operating on the checkout page, return this state. This state is returned via pay.orderQuery and does not need to be reported via pay.notify. |
PAID | Payment successful | After funds are actually charged, APP SVR must immediately push this state to SUD via an active callback (Webhook), or explicitly return it in the query interface. |
CLOSED | Payment closed/canceled (terminal state) | If the user actively cancels the payment, does not pay before timeout, or the charge explicitly fails, APP SVR must feed this state back to SUD, so that SUD can release upstream business resources. |
REFUNDING | Refund in progress (not reported) | The in-progress state after APP SVR accepts a pay.refund request. SUD learns it via pay.refundQuery; it does not need to be reported via pay.refundNotify. APP SVR should prepare to return the funds. |
REFUNDED | Refund completed (terminal state) | APP SVR successfully completes returning the funds via the original route. |
REFUND_FAIL | Refund failed (terminal state) | APP SVR cannot complete the refund (e.g., account deactivation). This is a terminal state; no further status is reported via pay.refundNotify, and manual/financial intervention is required offline. |
5. APP API Integration Checklist
To implement the above flow, the application backend server (APP SVR) must provide the following four dimensions of capabilities and interfaces:
Payment request security validation API (Validate Payload API):
- Responsibility (internal call): Respond to the authentication request initiated by the APP client before invoking the underlying checkout.
- Requirement:
APP SVRmust decrypt and verify whether the signature inpay_payloadis valid and was indeed genuinely issued bySUD OP SVR. Once signature verification fails, the payment flow must be blocked to prevent a malicious client from bypassing SUD to forge a payment request.
Payment result callback API (Webhook/Callback):
- Responsibility: When the user completes the charge or the payment is closed, actively push the result to SUD (corresponds to: server-side dual-server status synchronization phase). The request message must include the explicit amount and currency of the actual charge.
Order status query API (Query API):
- Responsibility: Respond to the Active Order Polling requests initiated by SUD (corresponds to: active query mechanism). The response message must include the explicit amount and currency of the actual charge.
- Mandatory specification requirement:
APP SVRmust accurately returnPAID(paid),PAYING(paying), orCLOSED(closed/canceled). In particular, when the user actively cancels the payment on the APP checkout page, or the underlying charge explicitly fails, APP SVR must returnCLOSED, and must not continuously returnPAYING. Only when theCLOSEDstate is explicitly received canSUD OP SVRissue an "order closure instruction" to the game server to release the Game order.
Refund acceptance API (Refund API):
- Responsibility: Respond to the fallback refund request initiated by
SUD OP SVRdue to a game-side delivery exception or amount validation failure (risk interception) (corresponds to: exception refund fallback phase). - Requirement: Must support full refund operations by order number and return the explicit result of the refund acceptance. Repeated requests with the same
sud_refund_nomust return the samerefund_idand must not create a second refund; see the "Idempotency" section of pay.refund.
- Responsibility: Respond to the fallback refund request initiated by
For callback URL configuration, see: Payment Onboarding
