抖音开放平台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
zoneIdstring

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

2.64.0
currencyTypestring

币种,目前仅为“DIAMOND”

2.64.0
buyQuantitynumber

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

goodType为游戏币场景时必传,其他场景不传

2.64.0
goodTypenumber

支付场景

3.47.0
orderAmountnumber

goodType为道具直购场景时必传,代表道具现金价格,单位为【分】,如道具价格为0.1元,则回传10

3.47.0
goodNamestring

goodType为道具直购场景时,代表道具名称,长度限制小于等于10个字符,用于区分道具类型

3.47.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 汇率自动转换。

orderAmount 参数说明

  • 由于 goodType 需要在基础库版本 3.47.0 及以上才可支持,可使用
tt.canIUse('openAwemeCustomerService.object.goodType')

来判断是否支持,与其他支付方式做好版本兼容。

  • goodType 合法值
    • 0:默认值,表示游戏币场景
    • 1:游戏币场景
    • 2:道具直购场景

回调成功

object 类型,属性如下:

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

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

2.64.0

回调失败

object 类型,属性如下:

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

"openAwemeCustomerService:fail " + 错误详情

2.64.0

错误码

errorCodeerrMsgerrorType说明最低支持版本
999999zoneId should not be emptyD
参数错误
2.64.0
999999invalid paramD
参数错误
2.64.0
999988only support iOSD
2.64.0
999983platform auth denyD
2.64.0
999996用户未登录D
用户未登录
2.64.0
999999请求参数不合法D
请求参数不合法
2.64.0
111015app 不支持小游戏支付U
app 不支持小游戏支付
2.64.0
111016内部错误,支付失败F
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
111001当前用户未通过实名认证U
根据我国相关法律法规,需要提供用户真实身份信息
2.64.0
111002当前用户累计支付金额超过限制U
当前用户累计支付金额超过限制
2.64.0
111003支付失败U
小游戏支付请求过于频繁
2.64.0
111004交易存在风险U
交易存在风险
2.64.0
111005支付失败U
2.64.0
111006face authentication failedU
检测到疑似未成年下单,拉起人脸核验,人脸验证不通过
2.64.0
111007pay:fail error_tip_start_cash_register_failF
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
111008支付失败F
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
111009支付取消U
2.64.0
111010支付失败F
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
111014缺少参数D
2.64.0
111013其他错误F
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
999993internal errorF
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
111011调起收银台失败F
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
111017app 没有支付权限D
2.64.0
111018customId 为空或者不唯一D
2.64.0
111019订单状态不对F
小游戏框架内部错误,有需要请创建工单咨询
2.64.0
999988不支持iOS支付功能D
2.64.0
111012正在支付一起订单时,又发起了一笔支付请求D
2.64.0
999985网络异常U
2.64.0
111020付费礼包库存不足U
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", //用户自定义额外信息,支付结果回调信息包含此字段, 基础库版本低于1.55.0没有此字段 version: "v0.0.0", price: "30", }`, //extraInfo要转成字符串 success(res) { console.log("调用函数成功"); }, fail(res) { console.log("调用函数失败"); }, complete(res) { console.log("调用完成"); }, }); } else { // 游戏币 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 手机上进行支付调试。
目前支付测试暂未支持沙盒环境,测试过程中将使用真实金额进行支付,建议选择小额场景进行测试。