Skip to content

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 OP receives the payment request from the game side, it creates an order in SUD OP SVR and obtains a tamper-proof parameter package (pay_payload) with a strong signature. It then invokes the APP payment step. Before APP actually integrates with the underlying third-party gateway to charge, it must pass this parameter package through to APP SVR for legality validation. Only after validation passes is the actual funds settlement allowed to occur. What APP finally returns to SUD OP is only the front-end result (Frontend Only).
  • Front-end result synchronization and query trigger phase: After SUD OP receives the front-end result from APP, it immediately synchronizes the result to SUD OP SVR. This action immediately wakes up SUD OP SVR, triggering it to initiate an asynchronous payment result verification (Initiate async payment verification) with APP SVR.
  • Server-side dual synchronization and internal driving phase: To ensure the absolute security of funds and assets, APP SVR needs to establish dual safeguards with SUD 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): Once SUD OP SVR obtains the final funds status (PAID or CLOSED), it immediately terminates the query loop.
    • Amount reconciliation and interception (Validation): When SUD OP SVR obtains the payment-success status returned by APP 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 SVR will forcibly block delivery, immediately initiate a risk-control fallback refund to APP SVR, and transfer the game side into the order-closure flow, ensuring funds are not abnormally swallowed.
  • Exception refund fallback phase: If an exception occurs in SUD's internal flow (for example, internally driving game delivery fails), SUD OP SVR will initiate a refund request to APP SVR, and APP SVR must 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 EnumState MeaningAPP SVR-Side Core Responsibilities and Trigger Timing
PAYINGUser is payingWhen 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.
PAIDPayment successfulAfter 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.
CLOSEDPayment 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.
REFUNDINGRefund 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.
REFUNDEDRefund completed (terminal state)APP SVR successfully completes returning the funds via the original route.
REFUND_FAILRefund 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:

  1. 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 SVR must decrypt and verify whether the signature in pay_payload is valid and was indeed genuinely issued by SUD 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.
  2. 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.
  3. 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 SVR must accurately return PAID (paid), PAYING (paying), or CLOSED (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 return CLOSED, and must not continuously return PAYING. Only when the CLOSED state is explicitly received can SUD OP SVR issue an "order closure instruction" to the game server to release the Game order.
  4. Refund acceptance API (Refund API):

    • Responsibility: Respond to the fallback refund request initiated by SUD OP SVR due 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_no must return the same refund_id and must not create a second refund; see the "Idempotency" section of pay.refund.
  5. For callback URL configuration, see: Payment Onboarding