商户提现
收藏接口说明
- 该接口用于对可提现账户余额发起提现。
- 资金到账时间取决于银行或渠道的系统处理时效，一般情况下从发起提现到实际到账时间约 1-3 天，请您耐心等待！
- 保证每一笔提现传入 out_order_id 不同。
- 这个接口返回的状态码为 0 只代表受理成功，实际提现结果可通过提现查询结果进行查询。
- 针对于一个收款商户只允许一天在某一个渠道成功提现 5 次。
- 服务商发起提现请求，SALT 可以在第三方平台的设置->开发设置获取。
- 开发者发起的提现请求，SALT 可以在开发者后台的支付设置中获取。
使用限制
无
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/api/apps/ecpay/saas/merchant_withdraw/ |
| HTTP Method | POST |
| Scope | trade_basic.developer.payment_withdraw |
| 权限要求 | 商户接口提现 |
请求参数
请求头
access-token必填String
当非服务商时，调用https://open.douyin.com/oauth/client_token/生成的token
当服务商时，调用https://open.douyin.com/openapi/v2/auth/tp/token/生成的token
当服务商时，调用https://open.douyin.com/openapi/v2/auth/tp/token/生成的token
content-type必填String
示例：application/json
固定值"application/json"
Body
channel_type必填String
示例：alipay
提现渠道枚举值:
- alipay: 支付宝
- wx: 微信
- hz: 抖音支付
- yeepay: 易宝
- yzt: 担保支付企业版聚合账户
merchant_uid必填String
示例：M70372492301718182840
进件完成返回的商户号，商户号可以从以下方式获取
- 通过接口发起进件方式返回的merchant_id
- 通过进件页面链接[开发者获取小程序收款商户/合作方进件页面,服务商获取小程序收款商户进件页面,服务商获取服务商进件页面,服务商获取合作方进件页面]方式返回的merchant_id
- 通过开发者平台支付能力页面查看商户号
out_order_id必填String
示例：withdraw03456
外部单号（开发者侧）；唯一标识一笔提现请求
withdraw_amount必填Int64
示例：100
提现金额；单位分
app_idString
示例：ttdb96ad2b44aeff3301
小程序的 app_id；除服务商为自己提现外，其他情况必填
callbackString
示例："https://www.bytedance.com"
提现结果通知接口（开发者自己的https服务）；如果不传默认用支付设置中的回调地址
cp_extraString
示例：withdraw_demo
向开发者回调时，会原样存储在回调参数的extra字段中返回。
merchant_entityInt32
示例：1
抖音信息和光合信号标识:
- 不传或传0或1 按抖音信息提现；
- 传2按光合信号提现。
注意：channel_type为yzt时需要传2
thirdparty_idString
示例：ttc4a8b2155b82682f
小程序第三方平台应用 id。服务商发起提现请求的必填
请求示例
curl --location --request POST 'https://open.douyin.com/api/apps/ecpay/saas/merchant_withdraw/' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \ --data '{"channel_type":"BsCy9xp511","merchant_entity":6697559502044900581,"merchant_uid":"mNVpUXNihx","withdraw_amount":7288780048606911411,"thirdparty_id":"dO1rCFspDw","callback":"QrsNsb2YSx","out_order_id":"g5uWZmmK74","cp_extra":"ilPQJKzwXO","app_id":"hKDFaqyu8v"}'
响应参数
Body展开全部子属性
err_msg必填String
示例：success
错误提示信息
err_no必填Int32
示例：0
状态码 0 代表业务处理成功，具体错误码参见后文错误码章节
log_id必填String
示例：抖音开平统一日志id
dataStruct
返回数据信息
展开子属性
响应示例
正常响应示例异常响应示例
{ "err_no": 0, "err_msg": "", "log_id": "202310061616226C30B180133AE61392D7", "data": { "order_id": "N7078192267961368620", "merchant_entity": 1 } }
错误码
| HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
|---|---|---|---|
| 200 | 0 | 受理成功 | 受理成功 |
| 200 | 1000 | 内部错误，请稍后重试 | 稍后重试 |
| 200 | 1005 | 频率控制，请稍后重试 | 稍后重试 |
| 200 | 1091 | 功能暂未开启 | 功能未开启 |
| 200 | 1092 | 幂等，重复请求 | 本次请求的单据已经受理，如果想重新发起一笔提现，请换单重试。 |
| 200 | 2008 | token校验异常，请校验请求头中生成token的小程序appid/服务商id和请求参数是否一致 | 请校验请求头中生成token的小程序appid/服务商id和请求参数是否一致 |
| 200 | 2010 | 业务参数处理异常 | 检查请求参数，修改后重试 |
| 200 | 2042 | 小程序appid无效，请检查app_id字段 | 检查app_id字段信息是否有误 |
| 200 | 2047 | 服务商id无效，请检查thirdparty_id字段 | 检查thirdparty_id字段信息是否有误 |
| 200 | 2048 | 未查询到服务商与小程序的授权关系 | 检查服务商与小程序的授权关系 |
| 200 | 7007 | 账户不存在 | 请检查传入的商户号（merchant_uid）是否有误 |
| 200 | 8000 | 提现因风控被拦截 | 请自查站内信通知或提工单进行咨询 |
| 200 | 8001 | 提现余额不足 | 账户余额不足本次提现的金额， 请更换更小的金额 |
| 200 | 8002 | 账户状态异常 | 请检查传入的商户号（merchant_uid）在对应渠道（channel_type）是否进件成功 |
| 200 | 8003 | 账户状态异常已开通自动提现，不支持商户自行发起提现 | 请检查是否让运营或者产品同学配置了自动提现 |
| 200 | 8004 | 提现被风控拦截 | 风控拦截，可提工单进行咨询 |
| 200 | 8005 | 渠道结算信息不存在 | 请检查传入的商户号（merchant_uid）对应的结算信息是否有误 |
| 200 | 28001008 | access_token过期,请刷新或重新授权 | access_token过期,请根据请求头中token获取方式调用接口重新获取 |
