抖音开放平台Logo
开发者文档
控制台
  • API 概览
  • C# API
  • 开放接口
  • 转发
  • 群聊
  • 关注
  • 数据分析
  • 基础
  • 渲染
  • 设备
  • 文件
  • 位置
  • 媒体
  • 网络
  • 转发
  • 数据缓存
  • 广告
  • 界面
  • 支付
  • tt.openAwemeCustomerService
  • tt.requestGamePayment
  • 获取游戏币余额
  • 游戏币扣除接口
  • 游戏币赠送接口
  • 支付签名生成算法
  • 服务端回调接口
  • 主动查询订单状态
  • Worker
  • tt.requestGamePayment
    收藏
    我的收藏

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

    输入

    扩展属性描述如下:
    属性
    类型
    默认值
    是否必填
    说明
    最低基础库版本
    mode
    string
    支付的类型, 目前仅为"game"
    env
    number
    0
    环境配置,目前合法值仅为"0"
    currencyType
    string
    币种, 目前仅为"CNY"
    platform
    string
    申请接入时的平台,目前仅为"android"
    buyQuantity
    number
    金币购买数量,金币数量必须满足:金币数量*金币单价 = 限定价格等级(详见下方 buyQuantity 限制说明。开发者可以在字节小游戏平台的“支付”tab 设置游戏币单价)
    goodType为游戏币场景时必传,其他场景不传
    zoneId
    string
    1
    游戏服务区 id,开发者自定义。游戏不分大区则默认填写"1"。如果应用支持多角色,则角色 ID 接在分区 ID 后,用"_"连接
    customId
    string
    游戏开发者自定义的唯一订单号,订单支付成功后通过服务端支付结果回调回传
    必须具有唯一性,如果不传或重复传相同值,则会报错
    1.55.0
    extraInfo
    string
    游戏开发者自定义的其他信息,订单支付成功后通过服务端支付结果回调回传。字符串长度最大不能超过 256。
    1.55.0
    goodType
    number
    0
    支付场景
    3.47.0
    orderAmount
    number
    goodType为道具直购场景时必传,代表道具现金价格,单位为【分】,如道具价格为0.1元,则回传10
    3.47.0
    goodName
    string
    goodType为道具直购场景时,代表道具名称,长度限制小于等于10个字符,用于区分道具类型
    3.47.0

    mode 合法值

    说明
    game
    购买游戏币

    env 合法值

    说明
    0
    支付正式环境

    currencyType 合法值

    说明
    CNY
    人民币

    platform 合法值

    说明
    android
    android

    goodType 合法值

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

    输出

    fail 回调函数接收的对象扩展属性:
    属性
    类型
    说明
    errCode
    number
    错误码

    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

    goodType 限制说明

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

    示例

    if (tt.canIUse('requestGamePayment.object.goodType')) { // 道具直购场景 tt.requestGamePayment({ goodType: 2, // 道具直购 orderAmount: 10// 道具现金价值,单位分 goodName: "道具名称"// 道具名称 currencyType: "CNY", zoneId: "1", customId: "QWERTYUIDFxxxxx", extraInfo: '123', mode: "game", // 支付类型 env: 0, // 支付环境 platform: "android", 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.requestGamePayment({ mode: "game", // 支付类型 env: 0, // 支付环境 platform: "android", currencyType: "CNY", // 币种:目前仅为 "CNY" 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("调用完成"); }, }); }

    测试说明

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