单笔订单退款

最新更新时间：2021.11.25

请求将一笔订单发起退款（可支持部分退）

---

接口说明

请求URL： https://{domain}/os-base/refund/v1/open

请求方式： POST

公共请求参数

参数名	必填	类型	说明
access_id	是	string	开发者唯一标识
sign_type	是	string	固定传RSA2
time_stamp	是	long	请求时间，Linux时间戳，单位毫秒
sign	是	string	签名结果
data	是	string	将业务参数转为JSON字符串，然后使用BASE64编码的数据

详细签名方法请阅读接口加密方案

业务请求参数

名称	必填	类型	说明
ownerTradeNo	条件必填	string	商户传给开放平台的交易订单号, 与osTradeNo至少传一个
osTradeNo	条件必填	string	开放平台为商户生成的交易订单号, 与ownerTradeNo至少传一个
ownerRefundNo	否	string	商户自传的退款交易号,传此值时,会进行重复校验
refundFee	是	int	退款金额，单位分，要求不能大于支付订单总金额
refundReason	否	string	退款原因
callbackUrl	否	string	退款结果回调地址,需以https开头
ownerBusinessNo	否	string	商户创建的订单业务号
ownerPayTerminal	否	string	商户支付终端

公共响应参数

名称	必传	类型	说明
code	是	int	请求结果code,详细请参考错误码说明)
msg	是	string	请求结果描述，失败时会返回错误原因
data	否	object	请求结果返回的业务响应参数，若无业务参数则返回空

业务响应参数

名称	必传	类型	说明
osRefundNo	是	string	本次退款请求返回的退款单号，可用于主动查询退款结果

SDK方法

// 创建上传数据client
TyhPaymentClient client = TyhPaymentClient.create(TyhOptions.builder()
        .accessId(ACCESS_ID)
        .secretKey(SECRET_KEY)
        .allowUpload(Boolean.TRUE)
        .build());

// 构建退款请求参数
TradeRefundCmd refundCmd = TradeRefundCmd.builder()
        .ownerTradeNo("test_trade_2021125")
        .osTradeNo("os_trade_20211126")     // 该参数与ownerTradeNo二选一
        .ownerRefundNo("test_refund_20211126")
        .refundFee(500)
        .refundReason("退款原因")
        .callbackUrl("以https开头的通知回调地址")
        .build();

// 开始请求退款
try {
    Results<TradeRefundDto> results = client.tradeRefund(refundCmd);
} catch (Exception e) {
    e.printStackTrace();
}

入参格式

{
    "ownerTradeNo" : "owner_trade_32192182",
    "osTradeNo" : "os_trade_20211126",
    "ownerRefundNo" : "test_refund_20211126",
    "refundFee" : 500,
    "refundReason" : "退款原因",
    "callbackUrl" : "以https开头的通知回调地址"
}

出参格式：

{
  "code": 8888,
  "msg": "处理成功",
  "data": {
       "osRefundNo" : "os_refund_20211126"
  }
}

code 为 8888 表示操作成功，其它值则为失败，具体内容参见错误码说明)。