抖币支付
收藏预下单
频率限制：单个 appid 调用上限为 100 次/秒。
请求地址
POST https://webcast.bytedance.com/api/business/order/pre_create
请求参数
- •请求 Headers 属性数据类型必填说明 Byte-Authorization string 是详情可参考： 「签名及验签指南」Content-Type string 是必须包含 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
请求参数
- •请求 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-Authorization string 是详情可参考： 「签名及验签指南」Content-Type string 是必须包含 application/json
- •请求 Body
Body 需要以 JSON 格式填充
属性 | 数据类型 | 必填 | 说明 |
appid | string | 是 | 应用appID |
order_id | string | 是 | 订单ID，从"tt.payDiamonds"返回值获取 |
返回值
建议开发者对返回内容进行验签，验签详情可参考：「签名及验签指南」
- •正确返回的 JSON 数据包属性数据类型说明 order_id string 订单 ID，order_status number 订单状态（可选值如下：1-未知，2-已支付，3-余额不足关闭，4-异常关闭，5-预下单），open_id string 支付用户的 openID，pay_tag string 支付订单的标签，diamonds int64 支付订单抖币数量
- •异常返回的 JSON 数据包属性数据类型说明 errcode number 错误码，errmsg string 错误信息
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-Authorization string 是详情可参考： 「签名及验签指南」Content-Type string 是必须包含 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_list list 订单信息列表 size number 数据总量
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 数据包属性数据类型说明 errcode number 错误码 errmsg string 错误信息
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-Authorization string 是详情可参考： 「签名及验签指南」Content-Type string 是必须包含 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"}
