通知支付结果
收藏
我的收藏

订单支付成功/取消时，抖音开平交易系统会给向开发者的服务发起请求，将支付结果通知到开发者服务端。

使用限制

无

接口说明

•

由于网络波动等原因，可能会产生重复的通知消息，接入方需要做好幂等，正确处理。

•

回调可能存在延时，开发者可以通过主动请求查询订单信息，确认支付结果。

•

在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 HTTP 响应状态码设为 200，否则会认为通知失败进行重试。

•

结果通知失败的重试的时间间隔为 2s、4s、8s、16s、32s、64s、128s、256s、512s、1024s、 2048s、4096s、8192s、5h、5h、5h、5h、5h、5h、 5h，总共重试 20 次。

基本信息

基本信息
HTTP URL	•在`https://developer.open-douyin.com/microapp/${appid}/pay`页面设置的支付回调 URL。请注意替换地址中的${appid}为自己的实际appid值。 `ttf4d2826f6becc24001`为小程序的 `AppID`。 •在预下单回调响应中指定 notify_url
HTTP Method	POST

请求头

参见通用参数。

请求参数

参数名称	类型	是否必填	描述	示例值
msg	string	是	订单相关信息的 json 字符串	见请求示例
type	string	是	枚举值（支付结果回调为 payment）： •payment（支付成功/支付取消） •refund （退款成功/退款失败） •settle （分账成功/分账失败）	payment
version	string	是	固定值："2.0"。回调版本，用于开发者识别回调参数的变更	2.0

msg 字段

字段名	类型	是否必填	描述	示例值
app_id	string	是	小程序 app_id	ttcfdbb96650e33350
status	string	是	支付结果状态，目前有两种状态： •"SUCCESS" （支付成功） •"CANCEL" （支付取消）	SUCCESS
out_order_no	string	是	开发者系统生成的订单号，与抖音开平交易单号 order_id 唯一关联，长度 <= 64byte	ext_order_no_164318867591
order_id	string	是	抖音开平侧订单id，长度 <= 64byte	ot7057416814925531429
total_amount	int64	是	订单总金额，单位分支付金额为 = total_amount - discount_amount	9900
discount_amount	int64	否	订单优惠金额，单位分，接入营销时请关注这个字段	1100
pay_channel	int32	否	支付渠道枚举（支付成功时才有）： •1：微信 •2：支付宝 •3：银行卡 •10：抖音支付	1
channel_pay_id	string	否	渠道支付单号，如微信的支付单号，可能为空，可通过查询订单信息重新获取	5304340298302398023
cp_extra	string	是	预下单时开发者传入的透传字段（如果开发者未传，此字段为空），长度 <= 2048 byte	whatever
item_id	string	否	订单来源视频对应视频 id，可能为空，可通过查询订单信息重新获取，长度 <= 64byte	122211121
seller_uid	string	否	该笔交易卖家商户号，可能为空，可通过查询订单信息重新获取，实际存储的是int64类型的值	1222223333
event_time	int64	是	用户支付成功/支付取消时间戳，单位为毫秒	1643189272388
message	string	否	该笔交易取消原因，如： •"USER_CANCEL"：用户取消 •"TIME_OUT"：超时取消	USER_CANCEL
delivery_type	int	否	核销类型，开平告知是否可走闭环核销判断结果。 •0：非闭环核销，开发者自行处理券码生成及展示，通过 push_delivery 接口推送核销状态。 •1：闭环核销，开平负责生券，开发者使用核销组件展示，使用验券准备和验券接口核销。	1

请求示例

curl --location --request POST 'https://xxxxxxx.net/api/v2/result_callback?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json' \
--header 'Byte-Timestamp: 1698742798'\
--header 'Byte-Nonce-Str: D4Qr5GnHSZhKbG5EmqI2kHg7oMctULv2'\
--header 'Byte-Signature: cjtJ3XojTYQ8Jtpa7X41pZYmjBcct6wapwVf15qduyDtb7e5NxOU9M4B2B7z8J1LrqpkxrAvxKRvdCt3de0SIDznFrjs97plunWBtT35XufXPBa96XtiDYCTyqLNIhV'\
--data-raw='{
  "version": "2.0", //本次固定为2.0, 通过版本信息识别，用不同的结构体去解析上述关键参数
  "msg": "{\"app_id\":\"tt07e371xxxxxxx\",\"status\":\"SUCCESS\",\"order_id\":\"ot7057422956397414686\",\"cp_extra\":\"xxx\",\"item_id\":\"xxxxx\",\"seller_uid\":\"xxxxxx\",\"pay_channel\":1,\"message\":\"\",\"extra\":\"{\\\"cps_info\\\":\\\"poi\\\",\\\"share_amount\\\":\\\"299\\\"}\",\"event_time\":1643185090000,\"out_order_no\":\"ext_order_no_1643185079529\",\"total_amount\":1}",
  "type": "payment"
}'

msg 字段内容示例

//支付成功回调示例
{
    "app_id": "tt07e371xxxxxxx",
    "status": "SUCCESS",
    "order_id": "ot7057422956397414686",
    "cp_extra": "xxx",
    "item_id":"xxxxx",
    "seller_uid":"xxxxxx",
    "pay_channel": 1,
    "message": "",
    "extra": "",
    "event_time": 1643185090000,
    "out_order_no": "ext_order_no_1643185079529",
    "total_amount": 1,
    "discount_amount":0,
    "delivery_type":1
}


//支付取消回调示例
{
    "app_id": "tt07e371xxxxxxx",
    "status": "CANCEL",
    "order_id": "ot7057422956397414686",
    "cp_extra": "xxx",
    "message": "TIME_OUT",
    "event_time": 1643185090000,
    "out_order_no": "ext_order_no_1643185079529",
    "total_amount": 1,
    "discount_amount":0,
    "delivery_type":0
}

响应参数

参数名称	类型	描述	示例值
err_no	int64	错误码	0
err_tips	string	错误提示	success

响应示例

正常示例

//正常返回响应且http状态码为200
//注意：
//正常返回时一定要保证err_no和err_tips为下面标准返回方式，不然都认为失败，将会重试
{
  "err_no": 0,
  "err_tips": "success"
}

异常示例

//异常响应或http状态码为非200，
//字节服务端会不断重试
{
  "err_no": 1, //非0
  "err_tips": "system error"  //非success
}

通知支付结果收藏我的收藏

​使用限制​

​接口说明​

​基本信息​

​请求头​

​请求参数​

​msg 字段​

​请求示例​

​msg 字段内容示例​

​响应参数​

​响应示例​

​正常示例​

​异常示例​