抖音开放平台Logo
开发者文档
小游戏
控制台
  • API 概览
  • 开放能力
  • 基础
  • 渲染
  • 设备
  • 文件
  • 位置
  • 媒体
  • 网络
  • 游戏转发分享
  • 实时语音
  • 数据缓存
  • 系统
  • 广告
  • 界面
  • 支付
  • Worker

    • 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 手机上进行支付调试。​
    ​目前支付测试暂未支持沙盒环境，测试过程中将使用真实金额进行支付，建议选择小额场景进行测试。​
    ​