Skip to content

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;
}
FieldTypeDescription
sudTradeNoStringSUD business order number, used to uniquely identify this payment order
signDataStringOriginal 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
signatureStringSignature result, used to verify whether the payment request is trustworthy

signData Field Descriptions ​

signData is a JSON-formatted string that contains the following fields:

FieldRequiredTypeDescription
modeYesStringPayment scenario. Currently supported types: goods - direct item purchase; coin - game coins
envYesnumberEnvironment configuration: 0 - production environment; 1 - test environment
productIdConditionalStringProduct ID (required for direct item purchase scenarios)
unitPriceConditionalnumberUnit price of the product, in cents (required for direct item purchase scenarios)
quantityYesnumberPurchase quantity
currencyYesStringCurrency: CNY
outTradeNoYesStringBusiness order number
attachNoStringPass-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"
}
FieldTypeDescription
sudTradeNoStringSUD business order number, must match params.sudTradeNo from the request parameters

Payment Failure ​

On payment failure or cancellation, call:

java
handle.failure(retCode, retMsg);
ParameterTypeDescription
retCodeintError code; 0 indicates success, non-0 indicates failure
retMsgStringError 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(...) or handle.failure(...) after payment completes, fails, or is cancelled.
  • Order consistency: The sudTradeNo returned after a successful payment must match the params.sudTradeNo of this request, to avoid order mismatches.
  • Security verification: It is recommended that the App submit signData and signature to 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);
    }
}

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.failure

Notes ​

  • Callback required: Whether payment succeeds, fails, or is cancelled, you must call handle.success(...) or handle.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 sudTradeNo returned on success should match params.sudTradeNo from the request parameters.
  • Avoid duplicate callbacks: A single payment request should call back handle only 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 signData or signature fails, 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.