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;
}| 字段名 | 类型 | 说明 |
|---|---|---|
sudTradeNo | String | SUD 业务订单号,用于唯一标识本次支付订单 |
signData | String | 签名原文数据,用于 APP 或服务端校验请求合法性。signData 是 JSON 格式的字符串,字段说明见下方 |
signature | String | 签名结果,用于验证支付请求是否可信 |
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"
}| 字段名 | 类型 | 说明 |
|---|---|---|
sudTradeNo | String | SUD 业务订单号,需要与请求参数中的 params.sudTradeNo 保持一致 |
支付失败
支付失败或支付取消时调用:
java
handle.failure(retCode, retMsg);| 参数 | 类型 | 说明 |
|---|---|---|
retCode | int | 错误码,0 表示成功,非 0 表示失败 |
retMsg | String | 错误描述信息 |
示例:
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。
