抖币支付
收藏
我的收藏

预下单

频率限制：单个 appid 调用上限为 100 次/秒。

请求地址

POST https://webcast.bytedance.com/api/business/order/pre_create

请求参数

请求 Headers 属性数据类型必填说明 Byte-Authorizationstring 是详情可参考：「签名及验签指南」Content-Typestring 是必须包含 application/json
请求 Body

Body 需要以 JSON 格式填充

属性	数据类型	必填	说明
app_id	string	是	应用appID
out_trade_no	string	是	开发者订单号
pay_tag	string	是	付费点
diamonds	int64	是	抖币数量
open_id	string	是	用户openID
notify_url	string	是	订单支付成功通知回调URL。 URL必须为直接可访问的URL，不允许携带查询串，要求必须为https地址。
valid_time	int64	是	订单创建后多少秒内有效（建议游戏开始前x秒）

返回值

建议开发者对返回内容进行验签，验签详情可参考：「签名及验签指南」

属性	数据类型	说明
order_id	string	预下单ID

errcode 的合法值

错误码	错误信息	描述
-1	system error	服务内部异常
40001	request params are invalid	参数有误
40002	you don't have permission	通常为小程序没有该项能力
40003	data has exist	该订单号已存在
40007	over frequency control	调用频率过高
40014	required param not found	缺少必要的参数
50002	invalid params of signature	签名参数有误
50003	out-dated signed timestamp	签名参数上的时间戳距离当前时间过久
50004	verify signature fail	验签失败
50005	invalid url	NotifyURL不符合规范

返回数据示例

正常返回

{
  "order_id": "xxx"
}

错误返回

{
  "errcode": 400,
  "errmsg": "invalid params"
}

异步通知支付成功结果

开放平台完成抖币支付后，会把支付成功的订单信息回调通知给开发者服务器，开发者服务器接收到该消息后需要进行“游戏权益”的发放，并返回成功应答。

同一笔抖币支付订单，发放“游戏权益”务必保证幂等，不能出现“支付一次，多次发放‘游戏权益’”的问题，导致资损。

异步通知请求

注意 ⚠️：使用预下单时传递的notify_url字段作为回调通知 URL

请求方法

POST

请求参数

请求 Headers 属性数据类型必填说明 Byte-Timestampstring 是签名时间戳，与应答签名的时间戳意义一致，详情可参考：「签名及验签指南」Byte-Nonce-Strstring 是签名随机串，与应答签名的随机串意义一致，详情可参考：「签名及验签指南」Byte-Signaturestring 是签名值，与应答签名的签名值意义一致，详情可参考：「签名及验签指南」
请求 Body

Body 以 JSON 格式返回

属性	数据类型	必填	说明
status	number	是	支付状态： 1-未知，2-已支付，3-余额不足关闭，4-异常关闭，5-预下单；注意：当且仅当status=2的订单才进行“游戏权益”的发放！
app_id	string	是	appID
order_id	string	是	订单ID
open_id	string	是	openID 注意：此字段需要与开发者服务端存储的订单字段强校验
diamonds	number	是	抖币数量注意：此字段需要与开发者服务端存储的订单字段强校验
pay_tag	string	是	支付标签

请求 body 实例

{
  "status": 2,
  "mini_app_id": "xxxx",
  "order_id": "21003",
  "diamonds": 10,
  "open_id": "test1",
  "pay_tag": "1"
}

应答规则

如果开放平台收到开发者的应答不符合规范或超时未收到，开放平台会认为通知失败。开放平台会认为通知失败，接着会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但开放平台不保证通知最终能成功。

应答时道具发放结果通知 http 应答码为 200 或 204 才会当作正常接收，当回调处理异常时，应答的 HTTP 状态码应为 500，或者 4xx。

应答时不需要签名，开放平台只根据返回的状态码判断是否收到通知。

查询抖币支付订单结果

开发者服务器根据单个订单 ID 查询订单信息。

频率限制：单个 appID 调用上限为 500 次/秒。

请求地址

POST https://webcast.bytedance.com/api/business/diamond/query

请求参数

请求 Headers 属性数据类型必填说明 Byte-Authorizationstring 是详情可参考：「签名及验签指南」Content-Typestring 是必须包含 application/json
请求 Body

Body 需要以 JSON 格式填充

属性	数据类型	必填	说明
appid	string	是	应用appID
order_id	string	是	订单ID，从"tt.payDiamonds"返回值获取

返回值

建议开发者对返回内容进行验签，验签详情可参考：「签名及验签指南」

正确返回的 JSON 数据包属性数据类型说明 order_idstring 订单 IDorder_statusnumber 订单状态可选值如下：1-未知，2-已支付，3-余额不足关闭，4-异常关闭，5-预下单 open_idstring 支付用户的 openIDpay_tagstring 支付订单的标签 diamondsint64 支付订单抖币数量
异常返回的 JSON 数据包属性数据类型说明 errcodenumber 错误码 errmsgstring 错误信息

errcode 的合法值

错误码	错误信息	描述
-1	system error	服务内部异常
40001	request params are invalid	参数有误
40002	you don't have permission	通常为小程序没有该项能力
40007	over frequency control	调用频率过高
40014	required param not found	缺少必要的参数
50002	invalid params of signature	签名参数有误
50003	out-dated signed timestamp	签名参数上的时间戳距离当前时间过久
50004	verify signature fail	验签失败
50012	data does not exist	数据不存在

返回数据示例

请求

curl -v -d '{"appid":"ttxxx","order_id":"xxx"}' -H 'Byte-Authorization
: SHA256-RSA2048
 appid="ttxxx",nonce_str="DC10180A100073E70A48F195DA2AF2E6",timestamp="1623934869",key_version="1",signature="nwd1L3wCX+01/TVTkILeovF1DtYeghC1VHjrcjTHVkh7+gRaONEQkC2Y72Mw8JdSnIyeAtyp/pDHzyKGywjVqv5+JOBEhQG1/pvwNHN49wD26qg3AJL4hXw0fMJSRiTQEV1MszwDLuaabvo/qM9OXL9KyYiEPwVJqYtzmho4cHXT6mYgzNOW1xt5d7RDf4QO74JI3i4dtk9Uj8svJTrrBabML6AUcqcx2OP/7xukdaUgPdPf+IqmMG6GC4n52LUDogcL5n/osLdfHg9l6kW5gDcDjBfNDaggz07QMPHGdVao7pnQ2ub7VqcFIuY6Q3cBL7ndQdDGKrv+WBy5Q90QjQ=="' -H 'Content-Type: application/json' -H 'Accept: application/json' -X POST https://webcast.bytedance.com
/api/business/diamond/query

正常返回

{
  "order_id": "xxx",
  "order_status": 2,
  "open_id": "xxx",
  "pay_tag": "参与游戏",
  "diamonds": 10
}

错误返回

{
  "errcode": 400,
  "errmsg": "invalid params"
}

批量实时查询对账接口

为了保证开发者可以获取准确的抖币支付订单数据，开放平台提供“批量实时查询对账接口”，通过 appID 与时间范围批量查询抖币支付订单数据。

频率限制：单个 appID 调用上限 10 次/秒。

开发者务必接入“批量实时查询对账接口”，并保证对抖币支付成功的玩家发放相应“游戏权益”

对账时机建议：以 5 分钟作为时间区间，当前 5 分钟区间结束时，对账上一个 5 分钟区间的抖币支付订单数据。如下详细介绍：

时间区间：|0-5|5-10|10-15|........

对账时机公式：假设当前时间为 t（t 为 5 分钟的整数倍），请求“批量实时查询对账接口”，接口参数 start_time=t-10，接口参数 end_time=t-5，其他参数见“请求参数”部分。

对账时机描述：当时间处于“10”分时，请求“批量实时查询对账接口”，获取|0-5|分这个时间区间的抖币支付订单数据，并与开发者数据库的订单数据进行对账，对缺失的订单进行“游戏权益”的补发；当时间处于“15”分时，请求“批量实时查询对账接口”，获取|5-10|分这个时间区间的抖币支付订单数据，并与数据库的订单数据进行对账，对缺失的订单进行“游戏权益”的补发；以此类推。

请求地址

POST https://webcast.bytedance.com/api/business/diamond/reconciliation

请求参数

请求 Headers 属性数据类型必填说明 Byte-Authorizationstring 是详情可参考：「签名及验签指南」Content-Typestring 是必须包含 application/json
请求 Body

Body 需要以 JSON 格式填充

属性	数据类型	必填	说明
appid	string	是	应用appID
start_time	string	是	查询起始时间，如"2021-12-24 00:00:00"
end_time	string	是	查询终止时间，如"2021-12-24 00:05:00" 最长时间间隔不能超过24小时。
limit	number	是	取数量，最大为100
offset	number	是	从哪个位置开始取

返回值

建议开发者对返回内容进行验签，验签详情可参考：「签名及验签指南」

正确返回的 JSON 数据包(List)属性数据类型说明 order_listlist 订单信息列表 sizenumber 数据总量

order_list的 item 结构为

属性	数据类型	说明
order_id	string	订单ID
order_status	number	订单状态可选值如下：1-未知，2-已支付，3-余额不足关闭，4-异常关闭
open_id	string	支付用户的openID
pay_tag	string	支付订单的标签
diamonds	number	抖币数量
create_time	string	订单创建时间
room_id	string	房间号

异常返回的 JSON 数据包属性数据类型说明 errcodenumber 错误码 errmsgstring 错误信息

errcode 的合法值

错误码	错误信息	描述
-1	system error	服务内部异常
40001	request params are invalid	参数有误
40002	you don't have permission	通常为小程序没有该项能力
40007	over frequency control	调用频率过高
40014	required param not found	缺少必要的参数
50002	invalid params of signature	签名参数有误
50003	out-dated signed timestamp	签名参数上的时间戳距离当前时间过久
50004	verify signature fail	验签失败
50012	data does not exist	数据不存在

返回数据示例

正常返回

{
  "order_list": [
    {
      "order_id": "xxx",
      "order_status": 2,
      "open_id": "xxx",
      "pay_tag": "test",
      "create_time": "2006-01-02 15:04:05",
      "diamonds": 10,
      "room_id": "111"
    }
  ],
  "size": 1
}

错误返回

{
  "errcode": 400,
  "errmsg": "invalid params"
}

抖币支付 ACK 接口

为了保障平台用户的合法权益，在用户成功支付抖币后，确保游戏内对该用户发放了相应的游戏权益，平台提供“抖币支付 ACK 接口”，在游戏对抖币支付成功的用户发放了相应的游戏权益后进行调用；开发者务必接入，平台会统计游戏内抖币支付订单的 ACK 情况，根据统计结果做游戏的整体管控。

频率限制：单个 appid 调用上限为 100 次/秒。

只有抖币支付状态为已支付的订单才允许调用抖币支付 ACK 接口

请求地址

POST https://webcast.bytedance.com/api/business/diamond/order_ack

请求参数

请求 Headers 属性数据类型必填说明 Byte-Authorizationstring 是详情可参考：「签名及验签指南」Content-Typestring 是必须包含 application/json
请求 Body

Body 需要以 JSON 格式填充

属性	数据类型	必填	说明
order_id	string	是	抖币支付订单号
app_id	string	是	应用ID
diamonds	number	是	抖币数量
open_id	string	是	用户OpenID

返回值

建议开发者对返回内容进行验签，验签详情可参考：「签名及验签指南」

属性	数据类型	说明
ack_status	number	抖币支付ACK状态，为1表示ACK成功

errcode 的合法值

错误码	错误信息	描述
-1	system error	服务内部异常
40001	request params are invalid	参数有误
40002	you don't have permission	通常为小程序没有该项能力，或订单ID错误
40007	over frequency control	调用频率过高
50002	invalid params of signature	签名参数有误
50003	out-dated signed timestamp	签名参数上的时间戳距离当前时间过久
50004	verify signature fail	验签失败

正常返回

{
  "ack_status": 1
}

错误返回

{
  "errcode": 400,
  "errmsg": "invalid params"
}

错误码

上一篇：签名及验签指南

下一篇：数据开放

抖币支付收藏我的收藏

预下单

异步通知支付成功结果

异步通知请求

应答规则

查询抖币支付订单结果

批量实时查询对账接口

抖币支付 ACK 接口

错误码

抖币支付
收藏
我的收藏