体验抖音小游戏

游戏引擎

Unity 引擎适配

WebGL 方案与优化

BGDT 手册

接入

C# API

API 概览

开放能力

基础

设备

文件

媒体

网络

游戏分享

数据缓存

系统

界面

支付

支付请求

支付接入

游戏金币（仅抖音 lite）

宿主事件

抖音云模块

邀请模块

PlayerPrefs

调试工具

初始化

渲染

Cocos/Laya/Egret引擎适配

基础功能

开放能力

性能优化

支付请求
收藏
我的收藏

TT.OpenAwemeCustomerService

6.0.0 开始支持本方法

通过客服页面发起支付。

注意：

该模块对应小游戏接口小游戏接口：tt.openAwemeCustomerService

该模块对应旧版Unity SDK文档中的【钻石支付】

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

语法

public static void OpenAwemeCustomerService(JsonData options, 
    Action success, 
    Action<int, string> failed);

参数说明

属性名	类型	默认值	必填	说明
options	JsonData	--	是	格式详情
success	Action	--	是	打开客服页成功
failed	Action<int, string>	--	是	打开客服聊天页回调，参数为是否成功，true表示成功，false表示失败。

JsonData 内容格式：

	格式	默认值	是否必填	说明
buyQuantity	number	--	是	金币购买数量，金币数量必须满足：金币数量*金币单价 = 限定价格等级（详见下方 buyQuantity 限制说明。）
customId	string	--	是	游戏开发者自定义的唯一订单号，订单支付成功后通过服务端支付结果回调回传
currencyType	string	CNY	否	币种，目前仅为“DIAMOND”
zoneId	string	1	否	游戏服务区 id，开发者自定义。游戏不分大区则默认填写"1"。如果应用支持多角色，则角色 ID 接在分区 ID 后，用"_"连接
extraInfo	string	null	否	游戏开发者自定义的其他信息，订单支付成功后通过服务端支付结果回调回传。字符串长度最大不能超过 256。（强烈建议传入）

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

错误码

该接口错误码请参考小游戏API tt.openAwemeCustomerService 错误码。

代码示例

void OnPayButtonTapped()
{
    var options = new JsonData
    {
        ["buyQuantity"] = 1,
        ["customId"] = (System.DateTimeOffset.Now.ToUnixTimeMilliseconds() / 1000).ToString(),
        ["currencyType"] = "CNY",
        ["zoneId"] = "1",
        ["extraInfo"] = "sc pay test extra"
    };
    TT.OpenAwemeCustomerService(options, () =>
    {
        Debug.Log("OpenAwemeCustomerService success");
    }, (errCode, errMsg) =>
    {
        Debug.Log($"OpenAwemeCustomerService failed, errCode: {errCode}, errMsg: {errMsg}");
    });
}

TT.RequestGamePayment

6.0.0 开始支持本方法，WebGL也支持该方法

发起支付。

支付接入流程：

https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/api/payment/access-process。

抖音开发者平台接口文档：

https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/api/payment/tt-request-game-payment。

提示
调用该方法时，需要保证用户已经登录。可以调用tt.checkSession检测用户登录状态，以避免用户处于未登录状态时支付订单，在登录后无法关联订单与登录后的账户。
异常情况下，充值有可能存在游戏币延迟到账问题，建议游戏在收到支付结果回调后，向服务端轮询最新游戏币余额，间隔 3 秒，持续约 1 分钟，可以根据返回值的 save_amt 的变化来确定是否充值成功。同时也存在一些异常情况，导致充值成功后结果回调失败，因此建议游戏在启用游戏时主动查询游戏币余额，并且提供给用户主动刷新余额的功能。（不要将查询余额作为进入游戏的必要条件，查询失败时，可在显示余额的界面显示异常，不要拒绝用户进入游戏，更不要直接显示 0）强烈建议请求中填入 customId 和 extraInfo 字段（字段意义见下方表格），如果未填，支付结果回调将不包含游戏开发者的订单号，导致开发者无法确定回调是对应哪个订单，从而影响游戏道具发放。如果遇到此类问题，开发者可调用queryPayState 接口进行订单状态确认。
以上三条均属建议，供游戏参考。

语法

public static void RequestGamePayment(Dictionary<string, object> orderInfo,
    Action payCallback = null,
    Action<int, string> errCallback = null)

参数说明

属性名	类型	默认值	必填	说明
orderInfo	Dictionary<string, object>	-	是	订单信息，包含 mode、env、currencyType、platform、buyQuantity、zoneId、customId、extraInfo等信息
payCallback	Action	null	否	支付成功回调
errCallback	Action<int, string>	null	否	支付失败回调，由错误码和错误信息组成

orderInfo 的属性如下：

属姓名	类型	默认值	是否必填	说明
mode	string	--	是	支付的类型, 目前仅为"game"
env	number	--	是	环境配置，目前合法值仅为"0"
currencyType	string	--	是	币种, 目前仅为"CNY"
platform	string	--	是	申请接入时的平台，目前仅为"android"
buyQuantity	number	--	是	金币购买数量，金币数量必须满足：金币数量*金币单价 = 限定价格等级（详见下方 buyQuantity 限制说明。开发者可以在字节小游戏平台的“支付”tab 设置游戏币单价）
zoneId	string	1	否	游戏服务区 id，开发者自定义。游戏不分大区则默认填写"1"。如果应用支持多角色，则角色 ID 接在分区 ID 后，用"_"连接
customId	string	--	是	游戏开发者自定义的唯一订单号，订单支付成功后通过服务端支付结果回调回传必须具有唯一性，如果不传或重复传相同值，则会报错
extraInfo	string	null	否	游戏开发者自定义的其他信息，订单支付成功后通过服务端支付结果回调回传。字符串长度最大不能超过 256。

errCode 的值类型：

值	说明
-1	支付失败
-2	支付取消
-15001	缺少参数
-15002	请求参数不合法
-15003	app 不支持小游戏支付
-15006	app 没有支付权限
-15009	内部错误，支付失败
-15098	当前用户未通过实名认证
-15099	当前用户累计支付金额超过限制
-15101	customId 为空或者不唯一
-16000	用户未登录
-20002	交易存在风险，被风控策略拦截
2	正在支付一起订单时，又发起了一笔支付请求
3	调起收银台失败
4	网络异常
5	IOS 平台错误，当前平台不支持支付
6	其他错误
21113	检测到疑似未成年下单，拉起人脸核验，人脸验证不通过

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

代码示例

private void Test() {
    Dictionary<string, object> orderInfoParams = new Dictionary<string, object>();
    orderInfoParams["mode"] = "game";
    orderInfoParams["env"] = "0";
    orderInfoParams["currencyType"] = "CNY"; // 固定值: CNY。币种
    orderInfoParams["platform"] = "android";
    orderInfoParams["buyQuantity"] = 100;
    orderInfoParams["customId"] = (TimeUtils.GetCurrentTimeMs() / 1000).ToString();
    
    TT.RequestGamePayment(
        orderInfoParams,
        () =>
        {
            Debug.Log("Pay Success " + orderInfoParams["customId"]);
        },
        (errCode, errMsg) =>
        {
            Debug.Log("Pay failed - errCode: " + errCode + ", errMsg: " + errMsg, true);
        }
     );
}

支付请求收藏我的收藏

TT.OpenAwemeCustomerService

语法

参数说明

错误码

代码示例

TT.RequestGamePayment

语法

参数说明

代码示例

支付请求
收藏
我的收藏