开始接入
开始接入
更新时间：2024-11-18 06:11

接入流程可参考【 接入指南-3 时序图 】

# 1 登录鉴权

1.1 接口说明

客户端SDK登录成功后，建议cp通过服务端接口验证 AccessToken。

1.2 请求地址

以下都是正式环境，无测试环境，游戏开发者在接入测试时也使用SDK正式环境地址。

加速请求：

  • http://uglobal.ultrasdk.com/hu/v1/login/checkUserInfo.lg

SDK服务端API默认使用 HTTP POST application/x-www-form-urlencoded

1.3 请求参数

字段 必填 类型 字段说明
pcode 必须 String ProductId，SDK的产品ID
data 必须 String 加密后的业务数据，加密前的参数值参考1.4.1 参数生成规则
timestamp 必须 String unix 时间戳，格式如：1626320008
sign 必须 String 签名，参数生成规则

1.3.1 data参数

字段 必填 类型 字段说明
cUid 必须 String 渠道用户ID
cName 可选 String 渠道用户名称
accessToken 必须 String SDK客户端登录返回的Token

1.4 请求示例

curl https://uglobal.ultrasdk.com/hu/v1/login/checkUserInfo.lg -d 'data=eiJjVWlkIjNiMTAwMmtlIiwiY05hbWUiOyIiLCJhY2olc3NUb2dtbiI6ImV5SmphR0Z1Ym1Wc1gybGtJam9pSWl3aVpYaDBaVzVrSWpvaU1qRXdObnd5TlRWOE1DSXNJbTl6Wkd0ZmRYTmxjbDlwWkNJNklqQXdOakF3TVRWZk1UQXdNbWR0SWl3aWFYQWlPaUl4TWpjdU1DNHdMakVpTENKMGFXMWxJam94TmpJMk1EVTNPVEUyTENKemFXZHVJam9pTUdSbE56RXhOREZsTm1Oak16YzFOMkV6TldWak9EaGlOV1U0WWpabU5HUWlmUT09In0%3D&pcode=17188&sign=55f35601801fa4bb5a1644076076b15e&timestamp=1626057916'
1

1.5 响应参数

字段 名称 重要性 类型 说明
code 状态 必须 int 业务状态，0代表成功，不为0代表失败，具体错误可查看msg
msg 描述 可选 String 错误信息
cUid 渠道的用户id 必须 String -
cName 渠道的username 必须 String 转发第三方渠道用户名，若渠道不提供用户名，则返回为空字符串
channel 渠道码 必须 String ultra、baidu、ysdk
channelId 渠道ID 必须 int -
swLogin 切登录 可选 int 1: 表示是切登录过来的，默认没有该字段
curChannelUser 切登录 可选 int 当前登录的渠道用户信息，默认没有该字段
  • 说明:
    • 关于 唯一用户ID:

      • cUid 在 渠道内是唯一的，但在不同渠道之间是可能重复；

      • 请使用 channelId 与 cUid 的结合，来确定玩家的唯一账号;

        • 也可以使用 channel 与 cUid 组合

      • 官方渠道需要特殊处理，即「安卓渠道与iOS渠道的cUid是互通的」；

        • 官方国内与官方海外之间不互通；
        channelId channel 渠道名称
        7 ultra 国内Android
        8 iultra 国内iOS
        channelId channel 渠道名称
        3 iultraglobal 海外iOS
        4 ultraglobal 海外Android

1.6 响应示例

{
   "code": 0, // 0代表成功，不为0代表失败，具体错误可查看msg
   "msg": "",
   "timestamp": 1626060519882,
   "channel": "anzhi",
   "channelId": 29,
   "cUid": "20180112002346jUru7agnHW",
   "swLogin": 1,
   "ext": {},
   "curChannelUser": {
   	"cUid": "97422201",
   	"cName": "amengyan",
   	"channel": "iultra",
   	"channelId": 8
   }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

1.7 返回码

code不为0都为失败，具体错误，参考响应里的msg

code 说明
0 成功
-1 1.xxx参数不合法，如productId不合法
2.错误的 accessToken
3.签名校验失败
1 用户未创建
1002 错误的用户

# 2 支付回调

2.1 业务说明

当玩家支付成功后，SDK服务器会将支付结果通知给游戏（CP）提供的回调地址。

  1. 玩家支付成功: 以 SDK服务端收到、并验证支付结果通过 为准；
  2. 关于回调地址:

    • 请务必在【SDK管理后台 (opens new window)-出包->选择游戏->游戏配置->支付回调地址】中填写Callback_Url，或联系运营协助设置；

    • 请勿泄露真实回调地址；

  3. 回调请求方法: HTTP、POST、application/x-www-form-urlencoded
  4. 回调解密计算:
  5. 回调的响应值:
    • SUCCESS
      • 注意，只有这7个字符，不要有空白或其它字符；
      • 表示支付结果正常受理，流程结束。
    • ABORT
      • 表示 支付结果受理但有异常，流程结束，SDK 服务端不再重试通知该订单的结果；
      • 也可以返回 ABORT:描述信息 来补充少量说明信息；
    • 其它情况均表示 支付结果受理异常，流程未结束，SDK 会定时重试通知回调地址（见下文 回调重试策略）；

说明

客户端和中台都能配置回调地址，如果都配置，以中台配置的为准，如果想更改优先级，请联系客服

  1. 请求方法: POST

2.2 回调参数

字段 名称 重要性 类型 说明
data String 必须 密文，通知主要内容，需要解密。已做URLEncode编码，格式见下文
sign String 必须 签名

  • data解密后的基础字段说明:

    参数 类型 重要性 来源 描述
    amount Double 必须 SDK 成交金额，单位元（CNY）
    gameOrder Sring 必须 游戏 游戏订单号
    orderNo String 必须 SDK 整合sdk订单号
    status int 必须 SDK 交易状态，0表示成功
    selfDefine String 可选 游戏 透传参数
    channelUid String 必须 SDK 渠道的用户id
    payTime String 必须 SDK 交易时间yyyy-MM-dd HH:mm:ss
    channel String 必须 SDK 渠道类型
    channelId int 必须 SDK 渠道ID
    goodsId String 必须 SDK 渠道的档位ID
    goodsName String 必须 SDK 商品名称
    isTest int 必须 SDK 是否为母包测试，1为母包测试， 0为其他渠道

  • data解密后的额外字段说明，有代金券、iOS订阅、其他需求可使用

    参数 类型 重要性 来源 描述
    yx_is_in_intro_offer_period String 可选 SDK 订阅：是否处于介绍价格期仅国内iOS渠道下有该字段
    yx_is_trial_period String 可选 SDK 订阅: 是否处于免费试用期 仅国内iOS渠道下有该字段
    iap_sub_expire String 可选 SDK 订阅：过期时间 仅国内iOS渠道下有该字段
    iap_sub String 可选 SDK 订阅：是否是订阅仅国内渠道iOS下有该字段
    paytype String 可选 SDK 支付方式类型 仅国内渠道下有该字段
    yx_sub_type String 可选 SDK 支付方式子类型 仅国内渠道下有该字段
    yx_sub_type String 可选 SDK 支付方式子类型 仅国内渠道下有该字段
    dealAmount String 可选 SDK 使用了SDK代金券实际支付的金额 仅国内渠道下有该字段
    qkChannelId int 可选 SDK quicksdk的id
    quickChannelId int 可选 SDK quicksdk的id 等于 qkChannelId 值一样
    sandbox String 可选 SDK 是否是沙盒 等于 仅(国内/全球)渠道下有该字段
    iapSub String 可选 SDK 订阅：是否是订阅仅全球iOS渠道下有该字段
    iapSubExpire String 可选 SDK 订阅：订阅过期时间 仅全球iOS渠道下有该字段
    currency String 可选 SDK 币种 仅全球渠道下有该字段
    payType String 可选 SDK 支付方式类型 仅全球渠道下有该字段

2.3 回调数据示例

示例

data=eyJhbW91bnQiOjEuMCwib3JkZXJObyI6IkhVQTEwMTg2MTY0NDEyIiwicGF5VGltZSI6IjIwMjEtMDctMDUgMTQ6NDI6MzMiLCJnb29kc0lkIjoiMSIsImNoYW5uZWxVaWQiOiIxMTg1OTEzMzk3OTAxMTM5Iiwic2VsZkRlZmluZSI6IumAj%2BS8oOWPguaVsCIsImNoYW5uZWwiOiJodWF3ZWkiLCJxdWlja0NoYW5uZWxJZCI6MjQsInFrQ2hhbm5lbElkIjoyNCwiZ2FtZU9yZGVyIjoiY3BPcmRlcklkXzE2MjU0Njc2MTIxMzAiLCJnb29kc05hbWUiOiLllYblk4FJROiHquWumuS5iea1i%2BivleWVhuWTgS0wMSIsImNoYW5uZWxJZCI6MTEsInN0YXR1cyI6MH0%3D&sign=1741120cdda4b3a50fe59224595da88f
1

data解密后的示例

{
	"amount": 1.0,
	"orderNo": "HUA10186164412",
	"payTime": "2021-07-05 14:42:33",
	"goodsId": "1",
	"channelUid": "1185913397901139",
	"selfDefine": "透传参数",
	"channel": "huawei",
	"quickChannelId": 24,
	"qkChannelId": 24,
	"gameOrder": "cpOrderId_1625467612130",
	"goodsName": "商品ID自定义测试商品-01",
	"channelId": 11,
	"isTest": 0, // 是否为母包测试，1为母包测试， 0为其他渠道
	"status": 0 // 0代表成功，不为0代表失败
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

2.4 返回响应

  • SUCCESS
    • 注意，只有这7个字符，不要有空白或其它字符；
    • 表示支付结果正常受理，流程结束。
  • ABORT
    • 表示 支付结果受理但有异常，流程结束，SDK 服务端不再重试通知该订单的结果；
    • 也可以返回 ABORT:描述信息 来补充少量说明信息；
  • 其它情况均表示 支付结果受理异常，流程未结束，SDK 会定时重试通知回调地址（见下文 回调重试策略）；

2.5 回调重试策略

回调通知会在24小时内，每间隔10分钟通知一次，直至收到SUCCESS应答后停止。

苹果、谷歌、华为由于是小票机制校验，可能会存在小票延迟的情况，这样会导致长时间不会到账；客户端会有轮询机制上报小票，24小时之内如果成功都会通知游戏服务器

2.6 发货条件（非常重要）

支付回调的成功响应只能确保玩家完成了支付行为，CP 需要独立校验该订单的合法性（cp 订单号与 amount、goodId，userId 等是否匹配），确认无误后才可以发货，否则会有潜在的刷单风险。

需要 CP 独立校验的字段包括：

1、渠道id是否一致
2、用户信息是否一致
3、自定义信息是否正确
4、金额档位是否正确
5、订单号是否一致
6、其它 `根据实际游戏业务需要验证的字段进行判断`
1
2
3
4
5
6

# 3 支付退款

3.1 退款接口说明

  1. 在用户退款后，SDK服务器会将支付结果通知给游戏（CP）提供的回调地址。

  2. 退款支持渠道： 目前只支持 utral-海外iOS (渠道id：3)、utral-海外Android (渠道id：4)、utral-国内iOS (渠道id：8)

  3. 退款回调地址: 开始前请务必在【SDK管理后台 (opens new window)-游戏管理-游戏基础信息】中填写退款回调地址

  4. 请求方法: POST

3.2 退款回调参数

字段 名称 重要性 类型 说明
data String 必须 通知主要内容，需要解密。格式见下文
sign String 必须 签名

data各字段说明:

参数 类型 重要性 来源 描述
amount Double 必须 SDK 成交金额，单位元
gameOrder Sring 必须 游戏 游戏订单号
orderNo String 必须 SDK 整合sdk订单号
status int 必须 SDK 交易状态，0表示成功
selfDefine String 可选 游戏 透传参数
channelUid String 必须 SDK 渠道的用户id
payTime String 必须 SDK 交易时间yyyy-MM-dd HH:mm:ss
channel String 必须 SDK 渠道类型
channelId String 必须 SDK 渠道ID
goodsId String 必须 SDK 渠道的档位ID
refund int 必须 SDK 退款状态，1表示退款订单
refund_time String 必须 SDK 用户退款时间

额外字段说明，是代金券、iOS订阅、其他需求可使用

参数 类型 重要性 来源 描述
iap_sub_expire String 必须 SDK 订阅：过期时间 仅国内iOS渠道下有该字段
paytype String 必须 SDK 支付类型 仅国内iOS渠道下有该字段
dealAmount String 可选 SDK 使用了SDK代金券实际支付的金额 仅国内渠道下有该字段

3.3 退款回调数据示例

data解密后的示例

{
	"iap_sub_expire": "",
	"amount": 30,
	"orderNo": "HUA10********",
	"payTime": "2020-06-28 18:26:14",
	"goodsId": "****",
	"channelUid": "*****",
	"selfDefine": "****",
	"channel": "iultra",
	"sandbox": "",
	"iap_sub": "",
	"qkChannelId": 0,
	"gameOrder": "****",
	"refund_time": "2020-06-29 02:34:20",
	"goodsName": "****",
	"channelId": 56,
	"status": 0, // 0代表成功，不为0代表失败
	"refund": 1
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

3.4 退款回调返回响应

  1. SUCCESS (注意，只有这7个字符，不能有空白或其它字符）

  2. 通知的解密签名计算

3.5 退款回调重试策略 退款回调通知每间隔5分钟连续通知3次，在收到SUCCESS应答后即停止。

# 恭喜你完成SDK服务端接入，现在开始正式测试吧～

本文档对解决你的问题有所帮助？
本页目录