tt.openAwemeCustomerService
收藏
我的收藏

基础库 2.64.0 开始支持本方法，低版本需做兼容处理。这是一个异步方法。

发起抖音钻石支付

前提条件	•使用前请参考指引完成IM客服能力接入（运营 - 功能 - 客服管理 - 抖音IM客服），后续充值相关问题用户都会通过该客服进行咨询（请勿用绑定的抖音号进行支付测试，会导致无法拉起客服界面）（本步骤未完成报错：fail im disable） •接入本能力需要先开通【虚拟支付】和【钻石兑换】能力，请前往开发者平台 a.在「商业化」>「虚拟支付」申请开通能力，详细信息可参考支付能力接入介绍 b.超级管理员通过顶部提示条开通钻石兑换能力，详细信息可参考钻石兑换介绍及接入指引
业务背景	无
使用限制	•支持抖音，版本大于等于22.5.0时用户可使用 •支持抖音极速版 iOS，版本大于等于27.5.0时用户可使用 •支持红果短剧 iOS（7.0.7 及以上版本），番茄小说 iOS（7.1.1 及以上版本）、汽水音乐 iOS（19.1.0 及以上版本） •支持 unity 小游戏
注意事项	•调用该方法时，需要保证用户已经登录。可以调用 tt.checkSession 检测用户登录状态，以避免用户处于未登录状态时支付订单，在登录后无法关联订单与登录后的账户。 •异常情况下，充值有可能存在游戏币延迟到账问题，建议游戏在收到支付结果回调后，通过接口获取游戏币余额向服务端轮询最新游戏币余额，间隔 3 秒，持续约 1 分钟，可以根据返回值的 save_amt 的变化来确定是否充值成功。 •用户成功拉起收银台后即回调成功，未成功拉起收银台即回调失败，与实际支付结果无关，是否支付成功请通过服务端接口查询余额自行保证。
相关教程	无

语法

tt.openAwemeCustomerService(options)

参数说明

options 为 object 类型，属性如下：

属性名	类型	默认值	必填	说明	最低支持版本
extraInfo	string		否	游戏开发者自定义的其他信息，订单支付成功后通过服务端支付结果回调回传。字符串长度最大不能超过 256。（强烈建议传入）	2.64.0
zoneId	string		否	游戏服务区 id，开发者自定义。游戏不分大区则默认填写"1"。如果应用支持多角色，则角色 ID 接在分区 ID 后，用"_"连接	2.64.0
currencyType	string		否	币种，枚举值 •DIAMOND - 表示钻石，目前仅支持该类型注意-如果要感知用户实际支付的币种类型，请参考服务端支付结果回调回传信息中的currency字段信息	2.64.0
buyQuantity	number		否	游戏币购买数量。游戏币数量必须满足：*游戏币数量游戏币单价 = 限定价格等级（详见下方 buyQuantity 参数说明**。开发者可以在开发者平台的“支付设置”tab 设置游戏币单价） goodType为游戏币场景时必传，其他场景不传	2.64.0
goodType	number		否	支付场景，详见下方 goodType 说明	3.47.0
orderAmount	number		否	goodType为道具直购场景时必传，代表道具现金价格，单位为【分】如道具价格为0.1元，则回传10	3.47.0
goodName	string		否	goodType为道具直购场景时，代表道具名称，长度限制小于等于10个字符，用于区分道具类型	3.47.0
customId	string		是	游戏开发者自定义的唯一订单号，订单支付成功后通过服务端支付结果回调回传	2.64.0
success	function		否	接口调用成功的回调函数	2.64.0
fail	function		否	接口调用失败的回调函数	2.64.0
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）	2.64.0

buyQuantity 说明

限制说明：购买游戏币的数量，开发者可以在开发者平台的“支付设置”tab 设置游戏币单价, 换算成 RMB 必须满足以下价格档位，即 buyQuantity * 游戏币单价 = 限定价格等级。如：游戏币单价为 0.1 元，一次购买数量至少是 10 个。

限定价格等级（单位：元）

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 1288 1998 2998

汇率转换说明：当 currencyType 为 “DIAMOND” 时，平台按 1:10 汇率自动转换。

goodType 说明

由于 goodType 需要在基础库版本 3.47.0及以上才可支持，可使用tt.canIUse('openAwemeCustomerService.object.goodType')来判断是否支持，需与其他支付方式做好版本兼容

值	说明
0	默认值，表示游戏币场景
1	游戏币场景
2	道具直购场景

回调成功

object 类型，属性如下：

属性名	类型	说明	最低支持版本
errMsg	string	"openAwemeCustomerService:ok"，用户支付成功	2.64.0

回调失败

object 类型，属性如下：

属性名	类型	说明	最低支持版本
errMsg	string	"openAwemeCustomerService:fail " + 错误详情	2.64.0
errCode	number	错误码，对应信息可参考错误码说明	2.64.0
errNo	number	错误码，对应信息可参考错误码说明	2.64.0

错误码

errCode	errNo	errMsg	说明	最低基础库版本
-1	20000	openAwemeCustomerService:fail 支付失败	用户支付失败	2.64.0
-2	20000	openAwemeCustomerService:fail 支付取消	用户取消支付	2.64.0
-15002	20000	openAwemeCustomerService:fail 请求参数不合法	请求参数不合法	2.64.0
-15009	20000	openAwemeCustomerService:fail 内部错误,支付失败	小游戏框架内部错误，有需要请创建工单咨询	2.64.0
-15098	20000	openAwemeCustomerService:fail 当前用户未通过实名认证	当前用户未通过实名认证	2.64.0
-15099	20000	openAwemeCustomerService:fail 当前用户累计支付金额超过限制	当前用户累计支付金额超过限制	2.64.0
-15101	20000	openAwemeCustomerService:fail customId 为空或者不唯一	customId 为空或者不唯一	2.64.0
-16000	20000	openAwemeCustomerService:fail 用户未登录	用户未登录	2.64.0
-16001	20000	openAwemeCustomerService:fail 不支持iOS支付功能	暂不支持支付，请按照指引开通能力	2.64.0
-17006	20000	openAwemeCustomerService:fail buyQuantity illegal	buyQuantity参数异常	2.64.0
-20002	20000	openAwemeCustomerService:fail 交易存在风险	交易存在风险，被风控策略拦截	2.64.0
21113	20000	openAwemeCustomerService:fail face authentication failed	人脸校验失败	2.64.0
3	20000	openAwemeCustomerService:fail error_tip_start_cash_register_fail	拉起收银台失败，小游戏框架内部错误，有需要请创建工单咨询	2.64.0
4	20000	openAwemeCustomerService:fail 网络异常	用户网络异常	2.64.0
99	20001	openAwemeCustomerService:fail params.buyQuantity should be number, but got undefined	buyQuantity参数错误，其他参数错误也会有类似错误信息	2.64.0

扫码体验

无

代码示例

道具直购场景

if (tt.canIUse("openAwemeCustomerService.object.goodType")) {
  // 道具直购场景
  tt.openAwemeCustomerService({
    goodType: 2, // 道具直购
    orderAmount: 10, // 道具现金价值，单位分
    goodName: "道具名称", // 道具名称
    currencyType: "DIAMOND", // 币种：目前仅为"DIAMOND"
    zoneId: "1",
    customId: "QWERTYUIDFxxxxx", //开发者自定义唯一订单号。如不填，支付结果回调将不包含此字段，将导致游戏开发者无法发放游戏道具, 基础库版本低于1.55.0没有此字段
    extraInfo: '{"userId":"12xxx6","version":"v0.0.0","price":"30"}', //extraInfo要转成字符串
    success(res) {
      console.log("调用函数成功");
    },
    fail(res) {
      console.log("调用函数失败");
    },
    complete(res) {
      console.log("调用完成");
    },
  });
}

游戏币场景

tt.openAwemeCustomerService({
  currencyType: "DIAMOND", // 币种：目前仅为"DIAMOND"
  buyQuantity: 600, // 购买游戏币数量
  zoneId: "1",
  customId: "QWERTYUIDFxxxxx", //开发者自定义唯一订单号。如不填，支付结果回调将不包含此字段，将导致游戏开发者无法发放游戏道具, 基础库版本低于1.55.0没有此字段
  extraInfo: '{"userId":"12xxx6","version":"v0.0.0","price":"30"}', //extraInfo要转成字符串
  success(res) {
    console.log("调用函数成功");
  },
  fail(res) {
    console.log("调用函数失败");
  },
  complete(res) {
    console.log("调用完成");
  },
});

Bug & Tip

测试说明

方案	说明	图示	注意事项
在IDE中调用支付接口	在开发者工具中调用支付接口时，可验证接口传入参数有效性。参数校验通过后模拟器将展示支付二维码，对应真机上表现为拉起收银台		此二维码只用作能力模拟，无法真实进行扫码支付
在IDE中使用Mock面板	在开发者工具中调用支付相关JSAPI时，可通过该能力Mock多个支付场景，帮助开发者快速调试接口。		抖音开发者工具4.4.1版本及以上支持该功能，只用作能力模拟，无法真实进行支付
扫码/真机调试（推荐）	完整测试支付链路，使用开发者工具中的【预览/真机调试】功能，扫码后可在真机上拉起收银台		•目前暂不支持测试沙盒环境，在真机测试的过程中将使用真实金额进行支付，建议选择小额支付进行测试，大额场景检查收银台支付金额是否正确即可 •用户在不同App端或系统支付时收银台样式存在差异，开发者无需关注

tt.openAwemeCustomerService收藏我的收藏

语法