Skip to content

requestPayment ​

请求发起支付 ​

该方法用于处理 SDK 发起的支付请求。当游戏内需要购买道具、金币、会员或其他虚拟商品时,SDK 会调用该接口,由原 APP 侧负责拉起支付流程,并在支付完成后通过 handle 将支付结果回传给 SDK。


方法声明 ​

java
/**
 * 请求发起支付
 *
 * @param handle 用于向 SDK 返回处理结果的状态句柄。
 * @param params 请求参数
 */
void requestPayment(SUDOPStateHandle handle, SUDOPRequestPaymentParams params);

参数说明 ​

SUDOPRequestPaymentParams ​

java
public class SUDOPRequestPaymentParams {
    /**
     * SUD 业务订单号
     */
    public String sudTradeNo;

    /**
     * 签名数据
     */
    public String signData;

    /**
     * 签名
     */
    public String signature;
}
字段名类型说明
sudTradeNoStringSUD 业务订单号,用于唯一标识本次支付订单
signDataString签名原文数据,用于 APP 或服务端校验请求合法性。signData 是 JSON 格式的字符串,字段说明见下方
signatureString签名结果,用于验证支付请求是否可信

signData 字段说明 ​

signData 是一个 JSON 格式的字符串,包含以下字段:

字段名是否必填类型说明
mode是String支付场景,当前支持的类型有:goods - 道具直购;coin - 游戏币
env是number环境配置:0 - 正式环境;1 - 测试环境
productId特殊String商品 ID(道具直购场景必填)
unitPrice特殊number商品单价,单位为分(道具直购场景必填)
quantity是number购买数量
currency是String币种:CNY
outTradeNo是String业务订单号
attach否String透传数据

返回说明 ​

通过 SUDOPStateHandle 将支付处理结果返回给 SDK。

支付成功 ​

支付成功时调用:

java
handle.success(dataJson);

其中 dataJson 通常需要包含本次支付对应的订单信息,例如:

json
{
  "sudTradeNo": "SUD_ORDER_123456"
}
字段名类型说明
sudTradeNoStringSUD 业务订单号,需要与请求参数中的 params.sudTradeNo 保持一致

支付失败 ​

支付失败或支付取消时调用:

java
handle.failure(retCode, retMsg);
参数类型说明
retCodeint错误码,0 表示成功,非 0 表示失败
retMsgString错误描述信息

示例:

java
handle.failure(-1, "payment fail");

运行行为 ​

  • 由 SDK 触发:当玩家在游戏内发起购买行为时,SDK 会调用 requestPayment。
  • APP 负责支付流程:原 APP 收到请求后,需要根据 sudTradeNo、signData、signature 等参数进行订单校验,并拉起自身支付流程。
  • 异步闭环:支付通常是异步过程,APP 应在支付完成、失败或取消后,通过 handle.success(...) 或 handle.failure(...) 通知 SDK。
  • 订单一致性:支付成功后返回的 sudTradeNo 必须与本次请求的 params.sudTradeNo 一致,避免订单串单。
  • 安全校验:建议 APP 将 signData 和 signature 提交给自身服务端进行验签,确认支付请求合法后再继续支付。

代码示例 ​

java
@Override
public void requestPayment(SUDOPStateHandle handle, SUDOPRequestPaymentParams params) {
    // params.sudTradeNo: SUD 业务订单号
    // params.signData: 签名数据
    // params.signature: 签名

    // 1. 可先将订单信息提交给 APP 服务端进行验签和下单
    // 2. 验签通过后,拉起 APP 自身支付流程
    // 3. 支付完成后,将结果通过 handle 回传给 SDK

    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 调用 requestPayment
        ↓
APP 接收 sudTradeNo / signData / signature
        ↓
APP 请求自身服务端进行验签
        ↓
验签通过后创建或确认支付订单
        ↓
APP 拉起支付渠道
        ↓
用户完成支付 / 取消支付 / 支付失败
        ↓
APP 查询或确认最终订单状态
        ↓
通过 handle.success 或 handle.failure 回调 SDK

注意事项 ​

  • 必须回调:无论支付成功、失败还是取消,都需要调用 handle.success(...) 或 handle.failure(...),否则 SDK 侧可能一直等待支付结果。
  • 不要提前成功:建议在支付渠道返回成功并且服务端确认订单成功后,再调用 handle.success(...)。
  • 订单号一致:成功返回的 sudTradeNo 应与请求参数中的 params.sudTradeNo 保持一致。
  • 避免重复回调:同一次支付请求只应回调一次 handle,避免 SDK 收到重复支付结果。
  • 处理用户取消:如果用户主动取消支付,建议使用明确错误码和错误信息,例如:
java
handle.failure(-2, "payment cancelled");
  • 处理验签失败:如果 signData 或 signature 校验失败,应直接返回失败,例如:
java
handle.failure(-3, "signature verify failed");
  • 网络异常处理:如果支付结果暂时无法确认,建议 APP 侧先查询服务端订单状态,确认最终结果后再回调 SDK。