跳到主要内容

接口说明

提示

OmniSDK 是一个聚合 SDK，提供了账号、支付、事件统计等功能模块，游戏 CP 方完成一次对接后即可在各个应用商店平台和第三方发布渠道进行游戏发布。

接受支付结果通知(游戏侧实现)​

SDK 服务器在验证订单支付成功后，会通过 CP 提供的 HTTP 接口通知游戏发放商品道具，通知请求中会有订单的详细信息， CP 方在验证无误后即可发放商品，并回复 success. SDK 服务端收到回复后，会将订单状态由支付成功更新为交易成功。

警告
  1. 接口不做平台区分，Google, iOS 或者其他平台共用一个接口
  2. 为了避免非法订单，CP 方请务必验证订单的商品 ID， 角色 ID，SDK UID 等关键信息无误后再进行发货
  3. 收到 CP 方返回为 fail 或者 未收到返回 时，SDK 服务器会在接下来的 24 小时每隔固定的事件通知 CP 方一次，直到失败次数达到上限，CP 方请保证幂等性
  4. CP 无论是以同步还是异步方式处理通知请求，务必保证对于回复了 success 的订单，玩家尽量快的收到相应商品

参数说明​

HTTP Method : Post

NameTypeDescriptionMust
order_idString平台订单id，例 : 872282619197394944Yes
app_idString平台 应用 id，例 : 1001Yes
app_channelString平台渠道 idYes
uidString平台提供给 CP 方 uid ，一般是 8 位数值型，例 : 18734638Yes
amtString订单金额，美元为单位，例 : 0.99Yes
goods_idString商品 id ，例 : com.kingsoftgame.xsjtest.iap.tier60Yes
third_order_idStringCP 订单号Yes
pay_itemStringCP 传递给 SDK 的透传字段，一般用于 CP 方做订单验证Yes
zone_idString游戏提供的服务器 id + 角色 id，范例 : 1_10001Yes
order_typeNumber设备类型: 1:android, 2:ios, 3:h5Mobile, 999:暂未未识别的设备类型Yes
pay_timeString支付时间，格式 : UNIX 时间戳Yes
sandboxBool是否是沙盒订单：true: 是，false: 否Yes
game_extString游戏客户端创建订单时的透传内容(支付接口中的 extJson 参数)No
signString签名参数, 详见文档 签名与验签Yes

返回结果​

//成功返回 success，失败需要返回具体原因
success
信息
  1. 关于 zone_id，pay_item 字段的数据流： CP 游戏客户端 -> 平台 SDK -> 平台服务器 -> CP 服务器。平台对这 2 个数据只用于存储订单信息，不做额外处理。CP 方可通过这 2 个透传字段做订单信息验证，比如 pay_item 存放游戏验证字符串或者其他信息
  2. zone_id，CP 方请传入正确的角色 ID 和 服务器 ID，便于后续的数据分析

订单回验​

游戏收到 SDK 推送的支付结果通知后，推荐游戏持 SDK 的订单号通过此接口来验证订单的合法性，如果订单合法，此接口会返回订单核心信息供游戏进行核对。

请求说明​

URL

GET https://api.seayoo.io/omni/purchase/verify-order/{:app_id}

参数说明

NameTypeDescriptionMust
app_idNumberURL 参数，SDK 分配给游戏的 APP IDYes
order_idNumberSDK 产生的订单号，支付结果通知时会携带，例 : 1462684197310341120Yes
nonceString一个随机字符串，需要保证一定时间内不重复，一般基于时间戳生成，例 : 8IBTHwOdqNKAWeKl7plt8g==Yes
signString签名参数, 详见文档 签名与验签Yes

返回结果​

响应

NameTypeDescriptionMust
codeNumber响应结果码，正常处理返回 0Yes
reasonString响应描述，正常处理返回 success，失败时描述具体原因Yes
dataString订单核心属性，具体参考下面的示例Yes

响应示例

{
  "reason": "success",
  "code": 0,  // code 不为 0 时按失败处理即可，其中 code=-6 表示订单未找到
  "data": {
    "sdkOrderId": 1462684126145589248,
    "gameOrderId": "60f809408e114b69ab000dea",
    "uid": 1392844584303874048,
    "productId": "com.sungray.dhlove.pack.51",
    "productQuantity": 1,
    "totalAmount": 1.49,
    "currency": "USD",
    "status": "pay-finish",
    "createTime": 1637566045,
    "paySuccessTime": 1637566045,
    "appId": 1064,
    "roleId": "618996",
    "serverId": "0",
    "deviceId": "06c436f1cb063689",
    "channelOrderId": "GPA.3316-3339-0468-97611..12",
    "paidAmount": 7.99,
    "extInfo": null,
    "sign": "cebc1a489e3686a5f8d62cfb263c0b04"
  }
}
信息

返回 data 中，需要关注一下 status 属性，只有在 status=pay-finish 时才表示订单成功，其他状态均为支付未完成

退款(游戏侧实现)​

对于 Apple, Google 等渠道，在支付成功后，玩家可能会退款，这时候，SDK 会通过 CP 提供的 HTTP 接口通知游戏退款。CP 方在处理退款逻辑成功后，接口需返回 success，否则，返回 fail.

警告
  1. 接口不做平台区分，Google、iOS 或者其他平台共用一个接口
  2. 请在确认订单信息无误后再进行退款
  3. 收到 CP 方返回为 fail 或者 未收到返回 时，SDK 服务器会在对 Google, iOS分别以每小时、30分钟通知 CP 方一次，直到失败次数达到上限，CP 方请保证幂等性

参数说明​

HTTP Method : Post

NameTypeDescriptionMust
order_idNumber平台订单id，例 : 872282619197394944Yes
zone_idString游戏提供的服务器 id + 角色 id，范例 : 1_10001Yes
uidNumber平台提供给项目方 uid ，是一个 19 位数值型，例 : 1675410369755131904Yes
role_idString游戏内的角色 IDYes
server_idString游戏提供的服务器 idYes
channel_order_idString支付完成后渠道返回的渠道订单号Yes
game_order_idString游戏自身产生的订单号Yes
signString签名参数, 详见文档 签名与验签Yes

返回结果​

//成功返回 success，失败需要返回具体原因
success

平台登录身份信息验证​

CP 端某些重要操作需要对用户的平台登录身份状态进行验证，可通过此接口进行验证。

请求说明​

POST https://api.seayoo.io/omni/auth/token-check

NameTypeDescriptionMust
app_idNumber平台 应用 ID，例 : 1001Yes
uidNumber平台提供给项目方 UID ，是一个 19 位数值型，例 : 1675410369755131904Yes
channel_idNumber平台渠道 IDYes
tokenString平台用户 token，在 SDK 客户端登录后会回传给游戏客户端Yes
signString签名参数, 详见文档 签名与验签Yes

返回结果​

//通过验证,code = 0 时通过验证, code 不为 0 时，reason 为具体原因
{
    "code":0,
    "reason":"success"
}

接受玩家下线通知(游戏侧实现)​

某些业务场景下需要踢玩家下线，比如用户在 SDK 侧做账号删除等，需要游戏按以下规则实现接口，然后把接口地址提供给 SDK 进行配置。

请求参数​

NameTypeDescriptionMust
app_idNumber游戏在 SDK 侧登记后分配的 App IDYes
event_typeString踢下线的事件类型: [user-deletion:用户删除]Yes
uidsString玩家登录后 SDK 分配的用户 ID，如果有多个，会使用半角逗号拼接Yes
signString签名参数, 详见文档 签名与验签

请求响应​

//成功返回 success，失败需要返回具体原因
success
最后于 更新