发起预扣费通知
收藏接口说明
开发者可以使用该接口，在发起代扣前通知用户（预扣费通知）。
- 仅当签约单在服务中（SERVING）状态可发起代扣。
- 仅抖音渠道签约的协议可调用该接口进行预扣费通知。
- 为保证用户体验，避免打扰用户，每天仅在7:00-22:00的时间内可发起预扣费通知。
- 周期内每一次扣费前只需要预通知一次。
- 签约后12h内进行扣费不需要预通知，如开发者调用此接口，会返回32010错误码，识别该错误码后可继续扣费。
- 支持传入预扣费的金额，传入的金额需不大于周期代扣模板上配置扣款的金额；并需要保证后续发起代扣的扣费金额不大于预通知时的金额。
- 如小程序有多个收款商户号，预通知时需要指定merchant_uid，且需要和发起代扣接口中传入的merchant_uid保持相同。
- 一次扣费前，预通知接口仅需调用一次，调用完成后，可于d+2到d+8日的7:00-22:00调用扣款接口进行扣费（如2025.01.01发起预通知，则可在2025.01.03-2025.01.09时间段内进行扣费）。
- 预通知成功后，在完成扣费前原则上不应该再次调用此接口，如继续调用字节服务端会直接返回，不会重复通知。
- 需要联系对接客服申请对应的测试模板进行预扣费通知测试，在开发者完成测试发布前，系统不会修改原有模板的扣费逻辑。因此建议开发者在系统中配置两条链路，链路A走原逻辑扣款，链路B走通知后扣款，当链路B经过充分测试并上线后，开发者可和客服沟通原有模板的切换时间节点，一旦抖音侧完成切换，对应模板会强制要求预通知后才可扣费，开发者也应及时将对应模板的扣费逻辑切换到链路B。
使用限制
无
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/api/trade_auth/v1/developer/pre_notify/ |
| HTTP Method | POST |
| Scope | trade_auth.developer.cycle |
| 权限要求 | 无 |
请求参数
请求头
access-token必填String
示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
示例：application/json
固定值"application/json"
Body
amount必填Int64
示例：2000
指定预扣费通知的金额（单位：分），不能超过模板配置金额。且需要保证后续发起代扣时扣费的金额不大于预扣费通知中传入的金额。
auth_order_id必填String
示例："ad7123123123123"
平台侧签约单的单号，长度<=64byte
merchant_uidString
示例："7123123123"
开发者自定义收款商户号，限定在小程序绑定的商户号内，如小程序绑定了多个收款商户号，调用该接口时需要和发起代扣接口中传入的商户号保持一致
请求示例
curl --location --request POST '/api/trade_auth/v1/developer/pre_notify/' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \ --data '{"amount":1000,"auth_order_id":"ad7123123123123","merchant_uid":"7123123123"}'
响应参数
Body
err_msg必填String
示例：success
错误信息
err_no必填Int32
示例：0
错误码
log_id必填String
示例："2023010128382726 "
抖音开放平台统一日志id
响应示例
正常响应示例异常响应示例
{ "err_no": 0, "err_msg": "success", "log_id": "2022092115392201020812109511046" }
切换单列布局错误码
| HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
|---|---|---|---|
| 200 | 10000 | 参数错误 | 对照错误提示和接口字段定义，检查对应的参数 |
| 200 | 12001 | 请求过于频繁 | 等待几秒后进行重试 |
| 200 | 13000 | 系统错误 | 请重试，多次重试不成功请联系平台客服 |
| 200 | 20000 | 订单信息不存在 | 检查auth_order_id/app_id传参是否正确 |
| 200 | 26006 | 商户号与小程序的支付产品不一致 | 检查app_id信息是否和merchant_uid匹配 |
| 200 | 26009 | 该小程序未开通支付能力，请先开通支付能力 | 根据错误信息完成对应配置 |
| 200 | 21046 | 订单收款商户号不合法 | 检查merchant_uid是否有效 |
| 200 | 32009 | 无法发送预通知 | 参照具体错误信息进行排查并检查协议是否有效 |
| 200 | 32010 | 无需发送预通知 | 该协议单无需发送预扣费通知/签约后首次扣费无需发起预通知或本周期已经发起过预扣费通知 |
