requestPayment
Request to Initiate Payment
This method handles payment requests initiated by the SDK. When the game needs to purchase items, coins, memberships, or other virtual goods, the SDK calls this interface, and the original App side is responsible for launching the payment flow and returning the payment result to the SDK via handle after payment completes.
Method Declaration
java
/**
* Request to initiate payment
*
* @param handle The state handle used to return the processing result to the SDK.
* @param params Request parameters
*/
void requestPayment(SUDOPStateHandle handle, SUDOPRequestPaymentParams params);Parameters
SUDOPRequestPaymentParams
java
public class SUDOPRequestPaymentParams {
/**
* SUD business order number
*/
public String sudTradeNo;
/**
* Signature data
*/
public String signData;
/**
* Signature
*/
public String signature;
}| Field | Type | Description |
|---|---|---|
sudTradeNo | String | SUD business order number, used to uniquely identify this payment order |
signData | String | Original signature data, used by the App or server to verify the request's legitimacy. signData is a JSON-formatted string. See the field descriptions below |
signature | String | Signature result, used to verify whether the payment request is trustworthy |
signData Field Descriptions
signData is a JSON-formatted string that contains the following fields:
| Field | Required | Type | Description |
|---|---|---|---|
mode | Yes | String | Payment scenario. Currently supported types: goods - direct item purchase; coin - game coins |
env | Yes | number | Environment configuration: 0 - production environment; 1 - test environment |
productId | Conditional | String | Product ID (required for direct item purchase scenarios) |
unitPrice | Conditional | number | Unit price of the product, in cents (required for direct item purchase scenarios) |
quantity | Yes | number | Purchase quantity |
currency | Yes | String | Currency: CNY |
outTradeNo | Yes | String | Business order number |
attach | No | String | Pass-through data |
Return Value
Return the payment processing result to the SDK via SUDOPStateHandle.
Payment Success
On payment success, call:
java
handle.success(dataJson);Here dataJson usually needs to contain the order information corresponding to this payment, for example:
json
{
"sudTradeNo": "SUD_ORDER_123456"
}| Field | Type | Description |
|---|---|---|
sudTradeNo | String | SUD business order number, must match params.sudTradeNo from the request parameters |
Payment Failure
On payment failure or cancellation, call:
java
handle.failure(retCode, retMsg);| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code; 0 indicates success, non-0 indicates failure |
retMsg | String | Error description |
Example:
java
handle.failure(-1, "payment fail");Runtime Behavior
- Triggered by the SDK: When a player initiates a purchase in the game, the SDK calls
requestPayment. - The App handles the payment flow: After receiving the request, the original App needs to validate the order using
sudTradeNo,signData,signature, and other parameters, and launch its own payment flow. - Asynchronous closed loop: Payment is usually an asynchronous process. The App should notify the SDK via
handle.success(...)orhandle.failure(...)after payment completes, fails, or is cancelled. - Order consistency: The
sudTradeNoreturned after a successful payment must match theparams.sudTradeNoof this request, to avoid order mismatches. - Security verification: It is recommended that the App submit
signDataandsignatureto its own server for signature verification, and proceed with payment only after confirming the request is legitimate.
Example Code
java
@Override
public void requestPayment(SUDOPStateHandle handle, SUDOPRequestPaymentParams params) {
// params.sudTradeNo: SUD business order number
// params.signData: signature data
// params.signature: signature
// 1. First submit the order information to the App server for signature verification and order creation
// 2. After signature verification passes, launch the App's own payment flow
// 3. After payment completes, return the result to the SDK via handle
int orderStatus = getOrderStatusFromPaymentResult();
if (orderStatus == 3) {
JSONObject jsonObject = new JSONObject();
try {
jsonObject.put("sudTradeNo", params.sudTradeNo);
} catch (Exception e) {
e.printStackTrace();
}
handle.success(jsonObject.toString());
} else {
handle.failure(-1, "payment fail,orderStatus:" + orderStatus);
}
}Recommended Implementation Flow
text
SDK calls requestPayment
↓
App receives sudTradeNo / signData / signature
↓
App requests its own server for signature verification
↓
After verification passes, create or confirm the payment order
↓
App launches the payment channel
↓
User completes payment / cancels payment / payment fails
↓
App queries or confirms the final order status
↓
Call back the SDK via handle.success or handle.failureNotes
- Callback required: Whether payment succeeds, fails, or is cancelled, you must call
handle.success(...)orhandle.failure(...); otherwise the SDK side may keep waiting for the payment result. - Do not report success prematurely: It is recommended to call
handle.success(...)only after the payment channel returns success and the server confirms the order succeeded. - Consistent order number: The
sudTradeNoreturned on success should matchparams.sudTradeNofrom the request parameters. - Avoid duplicate callbacks: A single payment request should call back
handleonly once, to avoid the SDK receiving duplicate payment results. - Handle user cancellation: If the user actively cancels payment, it is recommended to use a clear error code and message, for example:
java
handle.failure(-2, "payment cancelled");- Handle signature verification failure: If verification of
signDataorsignaturefails, return failure directly, for example:
java
handle.failure(-3, "signature verify failed");- Handle network exceptions: If the payment result cannot be confirmed for the moment, it is recommended that the App side first query the order status from the server and call back the SDK after confirming the final result.
