抖音开放平台Logo
开发者文档
小程序
控制台
  • OpenAPI 简介
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 评价
  • 交易工具
  • 交易系统
  • 担保支付（即将下线）
  • 进件
  • 支付
  • 退款
  • 发起退款
  • 退款结果查询
  • 退款结果回调
  • 退款常见问题
  • 结算及分账
  • 退分账
  • 提现
  • 获取对账单
  • 接口获取页面链接
  • 订单推送
  • 抖店绑定
  • 运营
  • 生活服务
  • 垂直行业
  • 其它
    • 可通过此接口将支付款退还给用户。

    使用限制

    无

    接口说明

      1.交易时间超过 1 年的订单无法提交退款。
      2.支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。
      3.申请退款总金额不能超过订单金额。
      4.微信渠道每个支付订单的部分退款次数不能超过 50 次，支付宝渠道不能超过 300 次。
      5.申请退款接口的返回仅代表业务的受理情况，具体退款是否成功，需要通过退款查询接口或者退款回调接口获取结果。
      6.银行卡支付的退款 7 天内到账，支付宝支付（余额、银行卡快捷支付等）的退款 3 个工作日内到账，微信支付（余额、银行卡快捷支付等）的退款 7 天内到账。（退款优先原路退，如用户使用尾号为 1234 的招行借记卡付款，则退款至用户尾号为 1234 的招行借记卡）。
      7.沙盒环境使用说明详见担保支付-沙盒环境。

    基本信息

    基本信息
    请求URL
    正式环境： https://developer.toutiao.com/api/apps/ecpay/v1/create_refund
    沙盒环境： https://open-sandbox.douyin.com/api/apps/ecpay/v1/create_refund
    请求方式
    POST
    接口频次
    50QPS(小程序app_id维度)

    请求头

    名称
    类型
    必填
    描述
    Content-Type
    string
    是
    固定值 "application/json"

    请求参数

    名称
    类型
    是否必填
    最大长度
    描述
    示例值
    app_id
    string
    是
    64
    小程序APPID
    tt07e3715e98c9aac0
    out_order_no
    string
    是
    64
    商户分配支付单号，标识进行退款的订单
    7056505317450041644
    out_refund_no
    string
    是
    64
    商户分配退款号，保证在商户中唯一
    401020220222383672284706009088
    reason
    string
    是
    100
    退款原因
    发错地址
    refund_amount
    number
    是
    11
    退款金额，单位分
    100，即1元
    sign
    string
    是
    344
    签名，详见签名DEMO
    d716027b7b5a91a3319a061d818cc9cc
    cp_extra
    string
    否
    2048
    开发者自定义字段，回调原样回传
    一些附加信息
    notify_url
    string
    否
    256
    商户自定义回调地址，必须以 https 开头，支持 443 端口
    https://douyin.com/callback
    thirdparty_id
    string
    条件选填
    64
    第三方平台服务商id，服务商模式接入必传，非服务商模式留空
    tta4bad2073b900000
    disable_msg
    number
    否
    -
    是否屏蔽担保支付的推送消息枚举值：
    1：屏蔽
    0：非屏蔽， 若接入POI，POI订单体系会发相关消息，所以不用再接收一次担保支付相关的消息，请传1
    1
    msg_page
    string
    否
    1024
    退款完成后推送给用户的抖音消息跳转页面，开发者需要传入在app.json中定义的链接，如果不传则跳转首页。
    pages/user/orderDetail/orderDetail?id=10000

    请求示例

    {
  "app_id": "tt07e3715e98c9aac0",
  "out_order_no": "7056505317450041644",
  "out_refund_no": "401020220222383672284706009088",
  "reason": "发错地址退款重新下单",
  "refund_amount": 12800,
  "sign": "d716027b7b5a91a3319a061d818cc9cc",
  "cp_extra": "一些附加信息",
  "notify_url": "https://douyin.com/callback"
}

    响应参数

    公共响应参数

    名称
    类型
    是否必填
    最大长度
    描述
    示例值
    err_no
    number
    是
    -
    详见错误码
    4004
    err_tips
    string
    是
    -
    详见错误描述
    退款金额超限

    业务响应参数

    名称
    类型
    是否必填
    最大长度
    描述
    示例值
    refund_no
    string
    否
    128
    担保交易服务端退款单号
    N7067465601190709538

    响应示例

    正常示例

    {
  "err_no": 0,
  "err_tips": "success",
  "refund_no": "N7067465601190709538"
}

    异常示例

    {
  "err_no": 5004,
  "err_tips": "小程序违规，相关接口已被封禁，请咨询相关同学后进行整改",
  "refund_no": ""
}

    错误码

    HTTP 状态码
    错误码
    err_no
    错误描述
    err_tips
    排查建议
    200
    0
    success
    注：该响应代表退款业务受理成功，系统开始处理退款。最终退款结果以异步回调或查询接口为准。
    200
    1000
    内部异常
    当前请求的退款可能受理成功也可能失败。 1、请使用相同的参数再次重试调用，需要保证退款请求号和退款金额不能变更。如果前一次退款请求已经受理成功，接口会幂等返回受理成功；如果前一次退款请求没有成功，接口会重试执行退款操作； 2、或者通过退款查询接口查询退款执行结果
    200
    1001
    业务繁忙，请稍后重试
    该笔退款未受理，请降低频率后重试
    200
    1090
    风控拦截
    联系小程序平台处理
    200
    1093
    系统异常，请稍后再试
    请稍后原单号重试，同一笔交易的退款至少间隔3s后发起
    200
    2000
    支付记录不存在
    检查请求中的支付单号或商户支付单号是否正确，确认后重新发起
    200
    2004
    当日金额或笔数超限，请明天再试
    退款金额或笔数超限，请明天再试，详见退款常见问题
    200
    2008
    签名校验异常，请使用正确的签名
    请使用正确的签名重新请求，详见签名DEMO
    200
    2010
    参数错误
    请检查参数后重试
    200
    2012
    旧平台账户订单不支持分账后退款
    建议联系买家进行线下退款处理
    200
    2013
    服务商无对应小程序分账授权
    联系小程序平台处理
    200
    2042
    小程序appid无效，请检查app_id字段
    检查app_id字段信息是否有误
    200
    2045
    请求来源不合法
    联系小程序平台处理
    200
    2047
    服务商id无效，请检查thirdparty_id字段
    检查thirdparty_id字段信息是否有误
    200
    2048
    未查询到服务商与小程序的授权关系
    检查服务商与小程序的授权关系
    200
    3000
    业务异常
    可通过查单接口确定退款状态和退款原因， 不能解决的联系小程序平台处理
    200
    3118
    原支付单状态非法，不允许退款
    查询支付是否为付成功状态
    200
    3141
    分账后退款，请等待分账全部完成后再试
    请等待分账全部完成后重试
    200
    4001
    退款已失败
    此笔退款已失败，请换单号重试
    200
    4003
    退款金额无效
    请检查退款金额是否正确，请求的退款金额不能大于支付总金额
    200
    4004
    退款金额超限
    请确认退款金额后原单重试
    200
    4010
    请求信息不一致
    幂等校验失败，同一个退款多次请求必须为同一个支付单并且金额相等，请检查参数后重试
    200
    4011
    已超过退款期限
    退款时间超过一年，无法退款，详见退款常见问题
    200
    4039
    退款次数超过限制
    建议联系买家进行线下退款处理
    200
    4100
    风控分账失败导致退款失败
    联系小程序平台处理
    200
    4101
    服务商与特约子商户关系上，该产品授权已被解除
    联系小程序平台处理
    200
    4102
    商户没有退款权限
    联系小程序平台处理
    200
    4103
    原支付交易被冻结
    联系小程序平台处理
    200
    4104
    商户担保产品权限已被冻结
    联系小程序平台处理
    200
    4105
    退款商家账户余额不足
    现无充值入口，可等待商家现金户入账，换单号重试
    200
    4200
    用户账户有异常行为，已被限制收款，本次交易无法完成
    方案一：建议联系买家进行线下退款处理；
    方案二：如果是微信或支付宝渠道退款，也可联系用户在微信或支付宝平台解除账号限制，解除限制后换单号重试
    200
    4201
    用户账户状态异常或注销，无法原路退款
    建议联系买家进行线下退款处理
    200
    4202
    用户账户状态异常无法退款
    商户现金户余额不足无法原路退且用户账户状态异常无法实现退款，请等待商户现金户余额充足再次发起退款或联系买家进行线下退款处理
    ​