跳转至

订单退款接口

使用场景

商家退款接口（非幂等，第二次请求外部退款号一致，会提示退款号已存在）。需要回调通知的话，请按要求提供接口

接口地址

参数说明

  • 公有参数

    发送请求是必须传入公共参数，详见公共参数

  • 私有参数

参数名称 是否必须 参数类型 长度限制 描述
outerTradeNo 是 string [2,50] 外部交易号，请以appid开头，例如：10000001101
outerRefundNo 是 string [2,50] 外部退款号，请以appid开头，例如：10000001201
reason 是 string [1,254] 退款原因
refundAmount 是 decimal [0.01,99999999.99] 本次退款的总金额
costAmount 否 BigDecimal (10, 2) 结算价，差价模式下，costAmount与tradeInfo必填其一
deliveryFee 否 decimal [0.01,99999999.99] 运费（结算价包含运费时，该字段不用传递）
notifyUrl 否 string [1,254] 通知url,非必填,退款完成时进行通知结果,与同步返回结果一致
tradeInfo 否 Object 订单信息
provinceCode 否 String [0,50] 消费省会编码
provinceName 否 String [0,50] 消费省会
cityCode 否 String [0,50] 消费城市编码
cityName 否 String [0,50] 消费城市
locationCode 否 String [0,50] 消费地区编码
locationName 否 String [0,50] 消费地区
shopName 否 String [0,100] 商家名称
shopPhone 否 String [0,50] 商家电话
shopAddress 否 String [0,500] 商家地址
poiCateCode 否 String [0,100] 商家一级品类code
poiCateDesc 否 String [0,100] 商家一级品类名称
poi2ndCateCode 否 String [0,100] 商家二级品类code
poi2ndCateDesc 否 String [0,100] 商家二级品类名称
poi3rdCateCode 否 String [0,100] 商家三级品类code
poi3rdCateDesc 否 String [0,100] 商家三级品类名称
recipientName 否 String [0,50] 收货人名称
recipientPhone 否 String [0,50] 收货人电话
recipientAddress 否 String [0,500] 收货人地址

TradeInfo对象

参数名称 是否必须 参数类型 长度限制 描述
thirdTradeNo 是 string [1,50] 第三方订单号
thirdRefundNo 是 string [1,50] 第三方退款单号
thirdRefundAmount 是 decimal [0.01,99999999.99] 退款总金额
thirdCostAmount 是 decimal [0.00,99999999.99] 结算总成本价
thirdDeliveryFee 否 decimal [0.00,99999999.99] 有运费必填 运费
isThirdOrders 是 int 1 是否有子订单 1有 2无
thirdOrders 否 object 无 有子订单必填。子订单信息列表，List 请按照商家拆分子订单
goodsDetail 否 object 无 无子订单必填。商品信息列表，List

注意 在返点模式下： thirdPayAmount与thirdCostAmount金额要保持一致

ThirdOrder对象

参数名称 是否必须 参数类型 长度限制 描述
outerTradeNo 是 String [2,50] 子订单的外部交易号，请以appid开头
thirdSubTradeNo 是 string [1,50] 第三方子订单编号
thirdSubRefundNo 是 string [1,50] 第三方子订单退款单号
thirdSubDeliveryFee 否 decimal [0.00,99999999.99] 有运费必填 运费
thirdSubRefundAmount 是 decimal [0.01,99999999.99] 子订单退款金额
thirdSubCostAmount 是 decimal [0.00,99999999.99] 子订单原结算成本价
goodsDetail 是 object 无 商品信息列表，List

GoodsDetail数据：

参数名称 是否必须 参数类型 长度限制 描述 示例
skuCode 是 String [1, 50] 商品编码 100013952938
skuName 是 String [1, 50] 商品名称 蒙牛 特仑苏脱脂纯牛奶 每100ml含3.6g乳蛋白 送礼推荐 250ml×16 礼盒装
skuCateCode 否 String [0,100] 商品一级品类code
skuCateDesc 否 String [0,100] 商品一级品类名称
sku2ndCateCode 否 String [0,100] 商品二级品类code
sku2ndCateDesc 否 String [0,100] 商品二级品类名称
sku3rdCateCode 否 String [0,100] 商品三级品类code
sku3rdCateDesc 否 String [0,100] 商品三级品类名称
quantity 是 Integer 32 数量 1
price 是 BigDecimal (10, 2) 商品单价 115.35
taxRate 否 BigDecimal (10, 2) 税率 13
taxCode 否 String [1, 50] 税收分类编码 1060406010000000000
taxUnit 否 String [1, 20] 开票单位 件
invoiceType 否 Integer 32 发票类型 (1:普票 2:专票) 2
amount 是 BigDecimal (10, 2) 商品金额（price * quantity） 115.35
gatAmount 是 BigDecimal (10, 2) 关爱通资产支付金额 115.35
costAmount 是 BigDecimal (10, 2) 关爱通结算价 115.35
freight 否 BigDecimal (10, 2) 运费（非单个商品的运费） 8

请求示例

POST /seller/v3/pay/syncRefund?access_token=b983eef183a789a693b91406f38b7e23&timestamp=1531039596&version=1.0.0 HTTP/1.1
Host: openapi.guanaitong.tech
Content-Type: application/json
Cache-Control: no-cache

{
"outer_refund_no":"10000001201",
"outer_trade_no":"10000001101",
"refund_amount":"10",
"reason":"部分退款测试-退款10积分,订单总额100"
}

返回参数说明

参数名称 描述
code 返回码。详见错误返回码。
msg 如果错误，返回错误信息。
data 如果没有错误，返回关爱通交易号

正确返回示例

{
    "code": 0,
    "data": "2018070820000016",
    "msg": "OK"
}

错误返回示例

{
    "code": 1000210001,
    "msg": "timestamp check failed!",
    "data": null
}

支付回调

请求URL

调用退款接口时,填写的notify_url

参数说明

参数名称 参数类型 描述
appid string 应用appid
outer_trade_no string 外部交易号
outer_refund_no string 外部退款号
refund_amount decimal 退款金额
trade_no string 关爱通交易号
timestamp string 时间戳，其值为1970-1-01 00:00:00.000到当前时刻的时间距离，单位是秒，时区为GMT+8（东八区）。如1469691921。关爱通接口允许的时间戳偏差为5分钟，偏差超过5分钟的请求将被拒绝。
sign string 签名，见 签名机制

请求示例

POST 商家URI,如:/syncRefund/notify HTTP/1.1
Host: 商家域名,如:test.guanaitong.tech
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

appid=10000001&outer_trade_no=10000001101&outer_refund_no=10000001201&
refund_amount=10.0&trade_no=2018070920000005&sign=edceccd3117ff3d32690a6caf23355a0b407074f&
timestamp=1531039298

返回参数说明

（1）notify只有在关爱通退款成功后才会发送；

（2）商家在收到了请求、校验通过后，请即时更新自己的订单状态，并返回success（不要带任何其他源码内容）；

（3）若关爱通的notify请求无响应或者接收的内容不是“success”，则认为通知失败，等一段时间后会再次请求（notify请求会在此后24小时内按递增时间间隔继续发送通知）；

（4）notify仅为通知，不论第三方返回成功或失败，都不会改变关爱通的订单状态；

正确返回示例

success

错误返回示例

fail
回到页面顶部