退款接口

1.概述

当用户在美团企业版发起退款时，美团企业版根据【退款接口】通知客户平台，为保证双方交易状态一致，客户平台需执行退款，并返回退款成功。

当接口出现网络超时或服务繁忙响应（错误码 501）时，美团企业版会重试退款，具体重试策略参考附录

2.接口基本信息

信息名称	信息描述
请求方式	POST
调用地址	客户平台提供
调用方	美团企业版
响应方	客户平台
响应超时时间	2.5s
调用限频	-

2.1 请求体

名称	类型	是否必填	示例	说明
accessKey	String	是	B3GFJIEHNEM1RLV-TK	美团企业版分配给客户的接入秘钥
content	String	是	UgxoCGPQIzoP	请求体内容，将请求参数JSON序列化后进行加密的结果值，参照：签名实例

content 加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳
traceId	String[64]	是	9042536864303509624	日志查询ID
entId	Long	是	46574	企业ID
method	String[64]	是	trade.third.refund	业务接口标识，此接口中的值为常量：trade.third.refund
tradeNo	String[64]	是	393033370136698	交易号
tradeRefundNo	String[64]	是	393033370136698	退款请求号，发起一次退款动作即产生一个新的tradeRefundNo。客户平台需要根据此流水号做退款幂等。
refundAmount	String	是	12.32	退款金额(不包含服务费)，单位元，支持小数点后两位
entRefundAmount	String	否	11.00	企业退款金额，单位元，精确到小数点后两位（不包含服务费）
businessDiscountRefundAmount	String	否	1.32	优惠承担退款金额，单位元，精确到小数点后两位
serviceFeeRefundAmount	String	否	0.32	退款服务费金额（空值表示没有服务费），单位元，支持小数点后两位

2.2 响应体

名称	类型	是否必填	示例	说明
traceId	String	是	9042536864303509624	日志查询ID
status	Integer	是	0	0为成功，其他错误见错误码
msg	String	是		失败时的错误描述
data	String	是	UgJn07uNgW7S7fJK0R0xVbaLxoCGPQIzoP-_K4Hmp4RduGszhm2mbUs2toZhCtXKP5JGXVTZ9kGts2Wx3IJQCd90ptMoJTDB0vu7mkedEr4KZCvZn77EZLssMC5SpXilmQ-5RXHzvMIT0ASH-IXepTP_O16U37QqCkEb5L1WLy4	响应数据，将响应参数JSON序列化后进行加密的结果值，解密秘钥使用secretKey参数，参照：签名实例

data解密后数据结构

名称	类型	是否必填	示例	说明
thirdRefundNo	String[45]	是	1547608646457	客户平台退款号。返回此号，表示客户平台受理退款动作成功，且会将退款给到用户。
refundDetails	jsonString	否	[ { "fundBearer":"cust", "detailAmount":100, "detailFlowId":"1234" }, { "fundBearer":"cust2", "detailAmount":100, "detailFlowId":"1234", "detailBatchNum":"DEBIT", "detailName":"商家代金券满50减3元", "detailExt":"{"other":"620000"}" } ]	退款明细（不含随单服务费）当第三方收银台企业配置资金构成配置时，必填

refundDetails 退款明细数据结构

名称	类型	是否必填	示例	说明
fundBearer	String	是	cust	资金承担方
detailAmount	String	是	3.00	资金承担方支付金额(不包含服务费)，单位元，支持小数点后两位
detailFlowId	String	否	1223343	营销券ID，或客户平台的流水ID，唯一
detailBatchNum	String	否	1242354363343	营销活动批次
detailName	String	否	商家代金券满50减3元	营销活动的名称
detailExt	String	否		扩展字段，可填关于营销活动的其他信息，要求格式为json

3.请求示例

3.1 请求示例

POST /refund HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Accept: application/json

{
    "version": "2.0",
    "accessKey": "CC1NRDRJLC76-TK",
    "content": "vg262c_ex0kPkuUnAB1EvTQIElbKCQ2HU7tuLtfQQzIvWRbV_F6tvhuH59WyKPdCPgPRyatIGgzWd286qHwWYxu6OZvEJWyjvrk5iIvtf1ELldBpm4y8KM8TQd0HsFYdIYRuPUwxBNhU2KqO_Fez8QDW45Tak_14ZLb-M4BHCxcziY1Cxk6IySXaFkEzPvH8SKPlUf3dMl9PvXNVHZQlB3Ge3qxLpF5hkCPwZmsfO8kZorxIDR2rDF0BdZKTkwJ6K02on13BSRCS4qt0G7c1cn4dGVQ4CTEDAqh57hmE-60XUtZW0ffitFhlwG9nEyn8aew75qzETAd1jteNfUC5ionbM0crCM6qYMfZO3gePRM"
}

content 明文

{
    "traceId": "-2023325447146468060",
    "ts": 1676356793925,
    "entId": 101442,
    "method": "trade.third.refund",
    "tradeNo": "1625384169263599669",
    "tradeRefundNo": "1625384316064239637",
    "refundAmount": "12.32",
    "entRefundAmount": "11.00",
    "businessDiscountRefundAmount": "1.32",
    "serviceFeeRefundAmount": "0.07"
}

3.2 响应示例

{
    "status": 0,
    "msg": "成功",
    "data": "nZCwXYIJoYbMzNblYcstxDXlnYUUtaUvsN_UIzNhzKs"
}

data 明文

{
    "thirdRefundNo": "1676356793",
    "refundDetails": "[
      {
        \"fundBearer\": \"cust\",
        \"detailAmount\": 100,
        \"detailFlowId\": \"1234\"
      },
      {
        \"fundBearer\": \"cust2\",
        \"detailAmount\": 100,
        \"detailFlowId\": \"1234\",
        \"detailBatchNum\": \"DEBIT\",
        \"detailName\": \"商家代金券满50减3元\",
        \"detailExt\": \"{\"other\": \"620000\"}\"
      }
    ]"
}

4.错误码

错误码	场景	场景描述
401	参数错误
402	参数缺失	如员工信息中的参数缺失，导致无法匹配到消费人信息
403	解密验签失败
410	支付单不存在
411	退款超额
412	订单已支付	美团企业版在客户平台下单时，若客户平台发现此交易单已支付并拦截下单，应响应此错误码
500	服务端异常
501	服务繁忙（可重试）
510	员工账户不可用	员工账户不可产生消费

5.附录

5.1 退款重试时机

次数	间隔（秒）
第1～3次	10
第4～6次	28800
第7～9次	86400

6.版本记录

版本号	版本日期	更新内容
V1.0	2022-11-05	初版