请求业务方退款审核

# 使用场景

当用户的某个订单申请了退款后,百度收银台会主动调用业务方的退款审核地址(开发者平台注册的退款审核地址)询问订单是否可退。

# 接口注意事项

  1. 幂等性:业务方接口需要具备幂等性平台技术术语---幂等性

  2. 超时时间:业务方接口的耗时要求小于 2s(超过 2s 会触发平台的超时重试,重试间隔:2min/4min/10min/30min/1h...);

  3. 返回值判断:errno 为 0 表示业务方已经成功收到该订单的退款审核信息,errno 不为 0 将认为是请求业务方退款审核接口失败,会发起重试(不限次数,重试间隔:2min/4min/10min/30min/1h...)。

  4. 异常退款:由于支付回调不成功导致的异常退款也会请求业务方退款审核。

# 请求参数说明

参数 参数名称 类型(长度范围) 参数说明 是否必需 样例
orderId 订单 ID Long 百度平台订单 ID 1068881223
userId 用户 ID Long 百度用户 ID 149235070
tpOrderId 业务方订单 ID string 业务方订单 ID 11119800
refundBatchId 退款批次号 String 百度平台退款批次号【幂等性标识参数】(用于重入判断) 149235070
applyRefundMoney 退款金额 Integer 退款金额,单位:分 100
rsaSign 参数签名 String 平台生成的 sign 全部参数参与签名,详见签名与验签

这里对全部参数签名是对平台的所有 POST 参数进行签名,如果商户 URL 里包含 GET 类型参数,不会参与签名。验签需要使用正确格式的平台公钥,可以在服务详情中查询,详见签名与验签第 8 项内容。

# 返回参数说明

名称 类型 是否必须 示例值 描述
errno Integer 0 返回码
msg String success 返回信息
data Object {"auditStatus":1,"calculateRes":{"refundPayMoney":100}} 返回数据

data 字段为 json 格式,参数如下:

名称 类型 是否必须 示例值 描述
auditStatus Integer 0 退款审核状态
calculateRes Object {"refundPayMoney":100} 全额退和部分退均要填写订单实际退款金额,单位:分。不论审核成功还是失败都需要填写本字段。

refundPayMoney 的值是以分为单位的整数。

auditStatus 枚举值说明如下:

auditStatus 枚举值 枚举说明
1 审核通过可退款
2 审核不通过,不能退款
3 审核结果不确定,待重试

auditStatus 重要性: 为必传参数(不传会认为接口返回出错),用来标识第三方的退款审核结果,平台根据审核结果执行退款或置为不可退款,若 auditStatus=3,百度收银台会视为审核结果不确定,会继续重试(重试频率:每 5min 一次),目前重试次数&重试期限不做限制(直到业务方返回审核通过或不通过等审核终态才结束重试)。

业务方返回 auditStatus=3,退款审核结果不确定,收银台不会给用户退款,可能会影响用户退款体验。

# 通知触发条件

当订单发起退款时,经平台初步校验认为可以退款的,会通过此接口向业务方请求退款审核。

# 业务方服务器参数获取

  1. 百度收银台是用 POST 方式发送通知信息,因此该页面中获取参数的方式,如:request.Form(“orderId”)、$_POST[‘orderId’];

  2. 百度收银台主动发起通知,该方式才会被启用;

  3. 服务器间的交互,不像页面跳转同步通知可以在页面上显示出来,这种交互方式是不可见的;

  4. 程序执行完后必须打印输出符合要求的 JSON 字符串。如果商户反馈给百度收银台的字符不是合法 json 或者解析出来的 errno 不为 0 会对此次请求发起重试;

  5. cookies、session 等在此页面会失效,即无法获取这些数据;

  6. 该方式的调试与运行必须在服务器上,即互联网上能访问。

# 业务方通知参数合法性验证

当百度收银台通过调用接口请求业务方订单退款审核时,业务方获得这些数据后,必须进行如下处理:

  1. 验证签名

    首先必需验证签名,然后验证是否是平台发来的通知,请参见签名与验签

  2. 业务数据处理注意事项

    业务方需要验证该通知数据中的 orderId 是否为业务方系统中创建的订单号,若非业务方订单,则表明本次通知是异常通知,务必忽略。在上述验证通过后业务方请审核判断该订单是否可以退款,将审核结果返回(若业务方返回可退款,平台会执行退款任务,退款成功后该笔订单不参与业务方的核销结算)。如果商户未正确处理业务通知,存在潜在的风险,商户自行承担因此而产生的所有损失。

# DEMO

  • 入参(REQUEST) DEMO:
https://xxx.tpbusiness.xxx/refundAudit?orderId=800020199&refundBatchId=100003588&rsaSign=Gzu1RT2toJSDthcLPG1ZWROI3jzvxFtO7yCPUqMT3L7cmnARncm5IIIQ6x+7S/02zWxr5FC9945WFSurO9kepVbU7YS6Lh9SEVQhvTO0YKG7TlLFTpH3Ik7JeHQalAKXYe/jNREDpHmTF9Jrq/wABeZGYXJn1M75A37h9zUt+kw=
  • 返回(RESPONSE) DEMO:
{"errno":0,"msg":"success","data":{"auditStatus":1, "calculateRes":{"refundPayMoney":100}}}

refundPayMoney 的值是以分为单位的整数,如不严格按照文档提示操作,会导致退款审核失败。