抖音开放平台Logo
控制台

商户余额查询

更新时间 2024-07-24 02:58:49
收藏
我的收藏

接口说明

  1. 查询商户各渠道账户余额。

使用限制

无

基本信息

名称描述
HTTP URL
https://open.douyin.com/api/apps/ecpay/saas/query_merchant_balance/
HTTP Method
POST
Scope
trade_basic.developer.payment_withdraw
权限要求
渠道账户详情查询

请求头

名称字段类型是否必填示例描述
access-tokenString是
当非服务商时，调用https://open.douyin.com/oauth/client_token/生成的token
当服务商时，调用https://open.douyin.com/openapi/v2/auth/tp/token/生成的token
content-typeString是application/json
固定值"application/json"

请求参数

Body

名称字段类型是否必填示例描述
channel_typeString是alipay

提现渠道枚举值:

  • alipay: 担保支付普通版支付宝
  • wx: 担保支付普通版微信
  • hz: 担保支付普通版抖音支付
  • yzt: 担保支付企业版聚合账户
merchant_uidString是M70372492301718182840

进件完成返回的商户号，商户号可以从以下方式获取

  1. 通过接口发起进件方式返回的merchant_id
  2. 通过进件页面链接[开发者获取小程序收款商户/合作方进件页面,服务商获取小程序收款商户进件页面,服务商获取服务商进件页面,服务商获取合作方进件页面]方式返回的merchant_id
  3. 通过开发者平台支付能力页面查看商户号
app_idString否ttdb96ad2b44aeff3301

小程序的 app_id。

在服务商为自己提现的情况下可不填，其他情况必填

merchant_entityInt32否2

抖音信息和光合信号主体标识:

说明：channel_type为yzt时，指定为2

thirdparty_idString否ttc4a8b2155b82682f

小程序第三方平台应用 id。

在服务商发起提现请求的条件下必填

请求示例

curl --location --request POST 'https://open.douyin.com/api/apps/ecpay/saas/query_merchant_balance/' \
--header 'access-token: 0801121846735352506a356a6' \
--header 'content-type: application/json' \
--data '{"app_id":"3VzstqT0ga","thirdparty_id":"hgZNa5N2DU","merchant_uid":"PnO3rRMe7i","channel_type":"msINa2xaQQ","merchant_entity":1494583206064440891}'

响应参数

Body

名称字段类型是否必填示例描述
err_msgString是success

错误提示信息

err_noInt32是0

状态码 0 代表业务处理成功，具体错误码参见后文错误码章节  

log_idString是

抖音开平统一日志id

响应示例

正常响应示例

{
  "err_no": 0,
  "err_msg": "",
  "log_id": "202310061616226C30B180133AE61392D7",
  "data": {
    "account_info": {
      "online_balance": 20,
      "withdrawable_balacne": 100000,
      "freeze_balance": 200000
    },
    "settle_info": {
      "settle_type": 2,
      "settle_account": "bytedance@163.com",
      "bankcard_no": "",
      "bank_name": ""
    },
    "merchant_entity": 1
  }
}

异常响应示例

{
  "err_no": 28001008,
  "err_msg": "access_token过期,请刷新或重新授权",
  "log_id": "202310061616226C30B180133AE61392D7"
}

错误码

http状态码错误码错误码描述排查建议
2000
受理成功
受理成功
2001000
内部错误，请稍后重试
稍后重试
2001005
频率控制，请稍后重试
稍后重试
2001091
功能暂未开启
功能暂未开启
2002008
token校验异常，请校验请求头中生成token的小程序appid/服务商id和请求参数是否一致
请校验请求头中生成token的小程序appid/服务商id和请求参数是否一致
2002010
业务参数处理异常
检查请求参数，修改后重试
2002042
小程序appid无效，请检查app_id字段
检查app_id字段信息是否有误
2002047
服务商id无效，请检查thirdparty_id字段
检查thirdparty_id字段信息是否有误
2002048
未查询到服务商与小程序的授权关系
检查服务商与小程序的授权关系
2007007
账户不存在
请检查传入的商户号（merchant_uid）是否有误
2008002
账户状态异常
请检查传入的商户号（merchant_uid）在对应渠道（channel_type）是否进件成功
2008005
渠道结算信息不存在
请检查传入的商户号（merchant_uid），提现渠道(channel_type), 主体标识(merchant_entity)对应的结算信息是否有误
20028001008
access_token过期,请刷新或重新授权
access_token过期,请根据请求头中token获取方式调用接口重新获取
​