抖音开放平台Logo
控制台

tt.openAwemeCustomerService
收藏
我的收藏

基础库 2.64.0 开始支持本方法,这是一个异步方法。

发起抖音钻石支付

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

语法

tt.openAwemeCustomerService(options)

参数说明

options 为 object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
extraInfostring

游戏开发者自定义的其他信息,订单支付成功后通过服务端支付结果回调回传。字符串长度最大不能超过 256。(强烈建议传入)

2.64.0
currencyTypestring

币种,目前仅为“DIAMOND”

2.64.0
zoneIdstring

游戏服务区 id,开发者自定义。游戏不分大区则默认填写"1"。如果应用支持多角色,则角色 ID 接在分区 ID 后,用"_"连接

2.64.0
buyQuantitynumber

游戏币购买数量。游戏币数量必须满足:游戏币数量*游戏币单价 = 限定价格等级(详见下方 buyQuantity 参数说明。开发者可以在开发者平台的“支付设置”tab 设置游戏币单价)

2.64.0
customIdstring

游戏开发者自定义的唯一订单号,订单支付成功后通过服务端支付结果回调回传

2.64.0
successfunction
接口调用成功的回调函数
2.64.0
failfunction
接口调用失败的回调函数
2.64.0
completefunction
接口调用结束的回调函数(调用成功、失败都会执行)
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 汇率自动转换。

回调成功

object 类型,属性如下:

属性名类型说明最低支持版本
errMsgstring

"openAwemeCustomerService:ok"。用户支付成功

2.64.0

回调失败

object 类型,属性如下:

属性名类型说明最低支持版本
errMsgstring

"openAwemeCustomerService:fail " + 错误详情

2.64.0

代码示例

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

错误码​

errNo
说明​
最低支持版本​
-1​
支付失败​
2.64.0​
-2​
支付取消,用户在确认弹窗点击取消​
2.64.0​
-17001​
参数检查不通过​
2.64.0​
-17006​
数量无效​
2.64.0​
-17008​
获取用户openId失败​
2.64.0​
-17010​
创建订单失败(常见原因:订单号重复)​
2.64.0​
-17011​
获取分布式锁失败(重复请求)​
2.64.0​
-16001​
暂不支持支付,请按照指引开通能力​
2.64.0​
-15006​
游戏未在抖音开放平台上进行支付配置(im disable)​
2.64.0​
-15098​
用户未实名​
2.64.0​
-15099​
用户不能充值​
2.64.0​
-15101​
customId 为空或者不唯一​
2.64.0​
4​
网络异常​
2.64.0​
5​
Android 平台错误,当前平台不支持支付​
2.64.0​
21113​
face authentication failed,人脸认证失败​
2.64.0​

测试说明​

开发者可通过抖音开发者工具上的真机调试功能生成二维码,使用抖音 App 扫码后即可在安卓和 iOS 手机上进行支付调试。​
目前支付测试暂未支持沙盒环境,测试过程中将使用真实金额进行支付,建议选择小额场景进行测试。​