WARNING

💡 模块名:GameHelper.Pay

描述

本模块支持微信、快手、抖音、TikTok、支付宝支付。

本系统提供内购支持；为了减小 SDK 包体，本模块设计成了一个可选模块，使用前请确认 SDK 包含支付模块。

各平台设备端支持情况

平台	安卓	IOS
微信	√	√
快手	√	√
抖音	√	√（仅抖音、抖音极速版客户端支持）
TikTok	√	√
支付宝	√（安卓、鸿蒙均支持）	√（iOS 15 及以上支持，iOS 15 以下不支持）

各平台接入须知

微信

必须根据 GameHelper.Pay.showPay 的结果控制支付入口是否显示。

抖音

支付必须同时接入抖音 IM 客服，发布端需先开通能力，研发通过 GameHelper.TTCustService.show() 拉起客服。
商品价格必须使用渠道限定档位：1、3、6、8、12、18、25、30、40、45、50、60、68、73、78、88、98、108、118、128、148、168、188、198、328、648、998、1998、2998 元。
iOS 使用钻石支付，商品标价需要按抖音钻石展示。详见官方钻石支付接入说明。

TikTok

如需在游戏中使用渠道豆子图标表示商品价格，请参考 TikTok Mini Games IAP Integration Guide。

支付宝

内购商品定价请参考渠道提供的价格档位（buyQuantity 限制说明）。

接入说明

准备工作

请确保在 SDK 初始化时正确传入 gameConfig 参数，首次接入时建议打开 gameConfig.json 文件搜索"payConfig"关键字，若未检测到该关键字表示缺少支付配置，联系配置文件提供方获取完整的配置。

关于支付事件

WARNING

💡 注意:

支付模块已在接口内自动上报以下支付事件，游戏层无需上报：

pay_click 支付按钮点击
pay_success 支付成功
pay_fail 支付失败
in_app_purchase 支付流程事件

iOSpay 参数

支持平台：微信

说明

该参数为一个可实时修改值的在线参数，仅在微信平台的 ios 设备上生效，配置 1 时表示隐藏支付入口，配为 0 时表示显示支付入口，用于控制 IOS 端是否显示支付入口；SDK 将其封装为 showPay 参数，游戏层只需要调用 GameHelper.Pay.showPay，根据结果处理游戏 UI；

获取商品列表

支付组件会从支付服务器获取商品列表并返回 Map；建议商品名称、价格等都从 prodName、prodPrice 等属性读取和显示。

详细接口说明

购买商品

调用购买商品接口时传入商品 ID，在 success 和 fail 回调内分别执行购买成功和购买失败的逻辑，普通小游戏可以在 success 回调内直接发放奖励，若为强联网游戏，请在收到游戏服务器的发货通知时发放奖励。

购买成功的 success 回调会返回一个对象，包含 prodId（商品 id）、prodName（商品名称）、price(单位:元)、currency(货币符号)、orderNo(自定义订单号)五个属性。

详细接口说明

异常订单查询

建议每次启动游戏时调用一次异常订单查询接口。回调对象中的 unshippedOrder 是待补单订单，fixOrder 是待复送订单，业务应根据商品 ID 发放对应奖励。

javascript

GameHelper.Pay.queryOrder({
  success: (list) => {
    console.log("待补单的订单有", list.unshippedOrder);
    console.log("待复送的订单有", list.fixOrder);
  },
  fail: () => console.log("查单失败"),
});

强联网游戏上报道具发放事件（仅强联网游戏需要上报）

因强联网游戏是游戏服务器通知游戏客户端发货，所以当游戏客户端发货通知后，修改支付服务器的道具发货状态；

javascript

GameHelper.Pay.buySuccessFromUser("1254455445");

支付测试

微信平台安卓端和 IOS 端支付流程不同
首次接入支付或者新增商品时可修改价格为较低数额，方便测试和减小测试数据对正式支付数据的影响
修改价格时请注意：由于微信平台对安卓端有金额限制，最低价格只能设置为 1 元；微信 IOS 端无限制，可设置为 0.01 元

接口索引

属性

属性	类型	描述	值
showPay	boolean	是否显示支付入口（按钮）	true:显示 false：不显示

showPay在各平台返回值逻辑处理如下：

微信

安卓端固定返回 true
ios 端会根据 iOSpay 参数值返回对应 boolean 值

方法

功能描述

获取所有商品信息列表

参数

Object callbacks

属性	类型	默认值	是否必填	说明
success	function	/	是	成功获取商品列表回调
fail	function	/	否	商品列表获取失败回调

callbacks.success 回调函数

参数

返回值是 Map，通过 prodMap.get(prodId) 获取商品信息。

属性	类型	说明
prodId	string	商品 ID
prodName	string	商品名称
prodPrice	number	商品价格
prodPriceCurrency	string	货币币种
rate	number	人民币与游戏币的换算比率，例如 1 元人民币 = 10 游戏币时，rate = 1 / 10 = 0.1
zoneId	string	游戏币分区

示例

javascript

GameHelper.Pay.getProductInfo({
  success: (prodMap) => {
    console.log("全部商品信息", prodMap);
    const product = prodMap.get("wx.example.product");
    console.log("指定商品信息", product);
  },
  fail: () => {
    console.log("获取商品列表失败");
  },
});

功能描述

购买商品

参数

Object orderCall

属性	类型	默认值	是否必填	说明
prodId	string	/	是	商品 id
success	function	/	是	成功获取商品列表回调
fail	function	/	否	商品列表获取失败回调
eventProperties	PAY_EVENT_PROPERTY	/	否	自定义的支付事件属性集合

orderCall.success 回调函数

参数

Object res

属性	类型	说明
prodId	string	商品 id
prodName	string	商品名称
price	string	商品的人民币价格
currency	string	货币符号
orderNo	string	支付服务器生成的自定义订单号

PAY_EVENT_PROPERTY

参数名称	类型	是否必填	说明
pay_param	string	否	自定义的字符串类型的属性参数
pay_param1
pay_param2
pay_param3
pay_param4
pay_type	number	否	自定义的数字类型的属性参数
pay_type1
pay_type2
pay_type3
pay_type4

示例

javascript

GameHelper.Pay.createOrder({
  prodId: "商品ID", // 请修改为正式的商品ID
  success: (res) => {
    GameHelper.CCComFun.showToast({ // 仅用于示例提示，实际运行时请删除
      title: "商品购买成功",
    });
    console.log("购买成功，回调参数是", res);
  },
  fail() {
    console.log("购买失败");
  },
  eventProperties: {
    pay_param: "payParamTest",
    pay_param1: "payParamTest1",
    pay_param2: "payParamTest3",
    pay_param3: "payParamTest3",
    pay_param4: "payParamTest4",
    pay_type: 0,
    pay_type1: 1,
    pay_type2: 1,
    pay_type3: 1,
    pay_type4: 1,
  },
});

功能描述

建议每次进入游戏时调用该接口，查询用户是否有已支付但未发放奖励的订单或待复送的订单，并根据返回结果发放对应奖励。

参数

Object callback

属性	类型	默认值	是否必填	说明
success	function	/	是	查询到异常订单时执行
fail	function	/	否	查询失败时执行

callback.success 回调函数

返回一个对象，包含以下两个订单数组：

属性	类型	说明
unshippedOrder	object[]	待补单的订单，没有订单时返回空数组
fixOrder	object[]	待复送的订单，没有订单时返回空数组

数组中的每个订单对象包含以下属性：

属性	类型	说明
currency	string	货币币种
orderNo	string	订单号
price	number	商品的人民币价格
prodId	string	商品 ID
prodName	string	商品名称

示例

javascript

GameHelper.Pay.queryOrder({
  success: (list) => {
    console.log("查单结果是", list);
    console.log("待补单的订单有", list.unshippedOrder);
    console.log("待复送的订单有", list.fixOrder);
  },
  fail: () => {
    console.log("查单失败");
  },
});

功能描述

仅强联网游戏需要调用，当强联网游戏收到游戏服务器的发货通知后，调用本接口上报道具发货状态

参数

string orderId

支付服务端返回的商品 id，由游戏服务器通知游戏客户端发货时一并下发

F&Q

Q:点击支付按钮后，出现“当前网络环境异常，请稍后再试”的提示

A:在控制台搜索“”关键字，检查所点击的商品按钮对应的商品 id 是否包含在 data 属性下。

1.引入和启动

2.公共底层模块

3.基础功能模块

4.平台运营周边功能

5.公共功能模块

7.广告系统

9.归因系统

描述

各平台接入须知

微信

抖音

TikTok

支付宝

接入说明

准备工作

关于支付事件

iOSpay 参数

获取商品列表

购买商品

异常订单查询

强联网游戏上报道具发放事件（仅强联网游戏需要上报）

支付测试

接口索引

属性

方法

F&Q

描述 ​

各平台接入须知 ​

微信 ​

抖音 ​

TikTok ​

支付宝 ​

接入说明 ​

准备工作 ​

关于支付事件 ​

iOSpay 参数 ​

获取商品列表 ​

购买商品 ​

异常订单查询 ​

强联网游戏上报道具发放事件（仅强联网游戏需要上报） ​

支付测试 ​

接口索引 ​

属性 ​

方法 ​

​

​

​

​

F&Q ​

描述

各平台接入须知

微信

抖音

TikTok

支付宝

接入说明

准备工作

关于支付事件

iOSpay 参数

获取商品列表

购买商品

异常订单查询

强联网游戏上报道具发放事件（仅强联网游戏需要上报）

支付测试

接口索引

属性

方法

F&Q