Virtual Payment Configuration - Direct IAP

Scope: Direct Item Purchase (Direct IAP) This document only covers the payment scenario where "a player directly purchases a specified item with cash, and the Game SVR is responsible for delivering that item." Another common scenario, "virtual currency recharge" (where a player first tops up a universal in-game token and then spends the token to buy items), will be described in a separate document. The two scenarios differ in order model, delivery timing, and reconciliation method, so do not mix the specifications in this document.

1. Overview

This document provides game developers (CP, Content Provider) with a core technical guide for integrating the SUD Direct IAP capability. It details how the game client initiates a payment call for a single item through the SUD SDK, and how the game server securely and reliably polls the delivery status and receives the delivery/order-close callback notifications issued by the SUD server.

2. Participants (Role Definitions)

2.1 Client-Side

• Player: The game player, the end user who initiates the purchase.
• SUD OP (SUD SDK): The SUD operations client SDK. As payment middleware, it receives instructions from the Game and handles the underlying logic of invoking the payment interface.
• Game: The game client. It is responsible for requesting a Game pre-order from the game server and calling the SUD SDK to bring up the payment interface.

2.2 Server-Side

• Game SVR: The game backend server. It is responsible for generating the internal game order (Game Order), providing the client polling interface, and receiving the asynchronous callback notifications officially issued by SUD to perform item delivery or order closure.
• SUD OP SVR: The SUD operations backend server. As the core of the payment platform, it is responsible for confirming the final, real fund status, and after confirmation, issuing secure operation instructions to the Game SVR.

3. Interaction Sequence

3.1 Key Steps Explanation

• Game Order Pre-generation Phase: When a player clicks to purchase a specified item, the Game must first request its own Game SVR to generate an internal business order (Game Order, which must contain the specific product_id), and then call the SUD SDK with this order's parameters to initiate the payment.
• Payment Processing and Frontend Result Sync Phase: The SUD system handles all the complex payment flows internally. The SUD OP synchronizes the frontend result to the server, thereby triggering the SUD OP SVR to verify the real funds at the underlying level.
  • ⚠️ Strict Warning: The game client must absolutely not rely on the returned frontend SUCCESS to deliver items directly to the player, as this carries an extremely high risk of payment being forged through standalone client cracking. All delivery actions must depend on server-side instructions.
• Client Polling Mechanism and UI Response Phase: After the Game receives the frontend result, it begins polling its own Game SVR to check whether the item has been credited. If the Game SVR returns success or failure, the client breaks out of the polling loop and updates the UI to inform the player; if it returns Pending, the client initiates the next status query request after a preset interval, until a terminal state of success, failure, or timeout is triggered.
• Core Webhook and Status Decision Phase:
  • Payment Success Branch (Result == PAID): The SUD OP SVR confirms that funds have been received and sends a delivery notification to the Game SVR. The Game SVR must verify the signature, and only after verification passes does it deliver the assets. If the Game SVR explicitly returns a business failure (such as an abnormal account), or the SUD OP SVR still times out after retrying the Webhook delivery up to the maximum number of times, the SUD OP SVR will automatically step in to execute a refund fallback (REFUNDING) to prevent erroneous refunds or dropped orders.
  • Payment Close Branch (Result == CLOSED): If the underlying layer finds that the player did not pay or actively canceled, the SUD OP SVR will issue an order-close notification. Upon receiving it, the Game SVR closes that Game order.

4. State Machine for Game

For the Game, there is no need to be concerned with the underlying retry and network reconciliation logic. It only needs to maintain the following simplified core state machine in its business database:

Status Enum	Status Meaning	Game-Side Action Guidance
PAID	Funds confirmed; SUD begins pushing the delivery Webhook	The Game SVR prepares to receive the callback and perform signature verification and delivery processing.
CLOSED	Closed (terminal state)	Trigger conditions: player cancellation, charge failure, or the actual payment amount does not match the original order (intercepted by SUD risk control). Upon receiving the order-close Webhook, the Game SVR terminates the order and releases the related business resources.
DELIVERED	Delivered (terminal state)	The Game SVR successfully processed the delivery Webhook, and the order is normally completed.
REFUNDING	Refunding (exception fallback)	Triggered by a Game SVR delivery failure. The Game side can mark its internal order as "delivery exception/refunded".

5. Core Development Guidelines for the Game Server (Game SVR)

To ensure the security of players' assets and the stability of the system, the Game backend R&D team must strictly follow the following three core development security principles when implementing the SUD Async Webhook:

1. Strong Signature Verification: When SUD sends a callback request, it attaches a highly encrypted signature string in the HTTP Header or Body. The Game SVR must use the public key or secret key provided by SUD to perform strict signature verification. Requests that fail signature verification must be rejected directly (return FAILED) to prevent external malicious forgery of delivery requests.
2. Anti-Duplication and Interface Idempotency: Affected by public network fluctuations, SUD may initiate multiple Webhook callback retries for the same order. The Game SVR must implement idempotency through a database unique constraint (such as the order number). The same order may only be successfully delivered or closed once. For duplicate callback requests, as long as the asset has already been delivered or the order has already been closed, SUCCESS must still be returned to SUD.
3. Strong Validation of Order Amount and Item Information: Before delivering high-value assets, the Game SVR must once again check the product_id (item ID), "actual payment amount", and "currency" in the SUD callback message, and perform a strict three-way comparison against the item value requested by the local Game order at the time it was brought up. Only when the item is consistent and the payment amount meets the sale price of that item is delivery allowed, strictly preventing black-and-gray-market tampering such as "gaining a lot for little" or "buying a high-priced item at a low price".

6. Operations Backend - Item Configuration

Before the client calls requestSUDPayment, item metadata (product_id, item name, unit price, currency, etc.) must first be created in the SUD operations backend for each sellable item. The product_id carried by the client when initiating the payment must be consistent with the one configured here, and the Game SVR will also use this product_id to complete the three-way comparison validation described in Section 5 when receiving the delivery Webhook. In other words, item configuration is an operational prerequisite step for integrating the payment capability; only after the configuration is complete can you proceed to the core interaction flow in Section 3.

6.1 Enter the Item Configuration Page

In "Virtual Payment - Payment Product Management - Item Configuration", configure the specific item information based on the Direct IAP capability.

6.2 Add an Item

After "Virtual Payment - Payment Product Management - Item Configuration - Add Item", set the relevant information for the item.