支付回调
业务场景
- 用户完成付款的订单，超级 SDK 服务端到账后，才会推送给 CP 支付回调地址，以便游戏客户端给用户发放物品
- 订单状态，仅支付成功后回调，其它状态不会发起回调
注意事项
- 校验下单数据和回调数据，避免篡改、跨渠道或跨角色的代充。以下表格为必须校验字段和不校验的风险
| 字段 | 字段说明 | 不校验的风险 |
|---|---|---|
| serverId | 游戏区服ID | 存在篡单风险，例如：黑厂可通过篡改信息，到别的渠道平台其他服下单 |
| openId | SDK用户唯一标识 | 存在篡单风险，出现益世界回调和 CP 下单的 openId 不同，B 用户给 A 用户进行代充 |
| amount | 支付金额，单位分 | 存在篡改风险，比如游戏内下单 648 元，被篡改为 1 元，再调用 SDK 的下单接口 |
| orderNo | CP订单号 | CP 服务端若单纯按回调订单号发货，要提防篡单风险 |
- CP 回调接口在响应之前，需做好签名和必须校验字段的值校验
- 当 CP 服务端收到支付成功通知，需立刻进行校验
- 校验不通过，需返回具体不通过原因，参考文档末尾的状态码说明
- 做好数据校验，有利于益世界 和 CP 在服务端的订单结果保持一致
- CP 服务端处理完订单必要的校验后，立马响应，异步发货
- 异步发货可提高响应性能，保证双方系统稳定性
- http 请求的重试，可能会导致数据重复推送，需要做好去重处理
- 可能存在网络异常，导致益世界调用 CP 服务端超时，CP 服务端实际已成功发货
- CP 服务端若收到同一订单的重复支付回调，要避免重复给玩家发货，造成损失
流程图
接口地址
地址由CP提供
接口说明
- 协议：HTTPS
- 方式：POST
- ContentType：application/json;charset=utf-8
- 请求 Header：
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| sdkApiVersion | int | 是 | 标识 SDK 的 API 版本号，目前使用新版 API 的数据格式和签名规则，值为：200 |
- 请求报文：
| 字段 | 类型 | 必需 | 参与签名 | 说明 |
|---|---|---|---|---|
| openId | string | 是 | 是 | SDK用户唯一标识 |
| serverId | string | 是 | 是 | 游戏区服ID |
| sdkOrderNo | string | 是 | 是 | SDK订单号 |
| orderNo | string | 是 | 是 | CP订单号 |
| amount | long | 是 | 是 | 支付金额，单位分 |
| payTime | string | 是 | 是 | 支付时间，格式：yyyy-MM-dd HH:mm:ss |
| timestamp | long | 是 | 是 | 毫秒时间戳 |
| extend | string | 是 | 否 | CP透传信息，不超过 1000 字符，不参与支付回调签名 |
| sign | string | 是 | 否 | 签名 |
- 响应报文：
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| code | int | 是 | 响应状态码 |
| msg | string | 否 | 响应描述 |
请求示例
{
"openId": "12345678912345678912345",
"serverId": "10158",
"sdkOrderNo": "2019010515034700909471",
"orderNo": "202151541584415",
"amount": 600,
"payTime": "2022-06-01 10:20:45",
"timestamp": 1654142913840,
"extend": "{\"data\":\"17751|401203600007331|司徒宏放|45|3\"}",
"sign": "3ae039629da605edaec7ae38523ec877"
}
响应示例
{
"code": 0,
"msg": "success"
}
签名规则
- 参数名区分大小写，按 ASCII 码从小到大排序（字典序）
- 只有值为 null 和名为 sign 的键值对，才不参与签名
- 使用 URL 键值对的格式，拼接成待签名字符串，签名 key 在最后拼接
- 将生成的签名与入参 sign 值作校验，验签忽略大小写
String sign = md5(k1=v1&k2=v2&k3=v3...&key=appKey);
调试示例
import cn.hutool.crypto.SecureUtil;
import java.util.HashMap;
import java.util.Map;
import java.util.TreeMap;
public class SignExample {
public static String getMd5Sign(Map<String, Object> params, String appKey) {
TreeMap<String, Object> sortedParams = new TreeMap(params);
StringBuilder builder = new StringBuilder(512);
sortedParams.forEach((k, v) -> {
if (v != null) {
builder.append(k).append("=").append(v).append("&");
}
});
builder.append("key=").append(appKey);
return SecureUtil.md5(builder.toString());
}
public static void main(String[] args) {
String appKey = "AaBbCcDdEeFfGgHh";
Map<String, Object> reqMap = new HashMap<>();
reqMap.put("openId", "12345678912345678912345");
reqMap.put("serverId", "10158");
reqMap.put("sdkOrderNo", "2019010515034700909471");
reqMap.put("orderNo", "202151541584415");
reqMap.put("amount", 600);
reqMap.put("payTime", "2022-06-01 10:20:45");
reqMap.put("timestamp", 1654142913840L);
System.out.println(String.format("发货签名:%s", getMd5Sign(reqMap, appKey)));
}
}
状态码
| 状态码 | 说明 |
|---|---|
| 0 | 成功 |
| 1000 | 未知错误 |
| 1001 | 验签失败 |
| 1002 | 参数缺失 |
| 1003 | 金额错误 |
| 1004 | openId错误 |
| 1005 | 游戏错误 |
| 1006 | 渠道错误 |
| 1007 | 订单不存在 |