# 申请退款

> phone | 2in1 | tablet

## 功能介绍

开发者可以调用该接口完成交易订单的退款。退款规则如下：

1. 不支持对同一笔交易单进行并发退款。

   * 一笔普通收单多次退款，时间间隔要在1分钟以上。
   * 合单多笔子单退款，时间间隔要在1分钟以上。
2. 订单退款只支持180天内的订单。

3. 申请退款成功不代表退款成功，退款场景是异步处理，需收到退款成功的异步回调通知才表示退款成功。

## 使用场景

在产生成功交易订单的前提下，开发者的应用/元服务可以通过该接口完成某笔订单的退款申请，退款成功后华为支付会回调退款结果给商户服务器。

## 使用约束

换单重试，视为新的业务订单，需开发者自行将新的业务订单关联业务原订单。接口重入规则说明如下（供参考）：

|重入判定字段|支持原单重入场景|建议换单重试场景|
|:------------------------|:-----------------------------------------------------------|:--------------------------------------------------------------|
|商户退款订单（mercRefundOrderNo）|发起退款请求失败，建议根据错误码（400000 RETRY_TOO_MANY错误码场景，需要换单重试）排查后，原单重试。|1. 400000 RETRY_TOO_MANY错误码场景，需要换单重试。 2. 多次部分退款场景下，每次需要换单后发起请求。|

## 接口原型

* **承载协议：** HTTPS POST

* **接口方向：** 开发者服务器 -> 华为支付服务器

* **接口URL：** https://petalpay-developer.cloud.huawei.com.cn/api/v1/aggr/transactions/refunds

* **数据格式：**

  请求消息：Content-Type: application/json; charset=UTF-8

  响应消息：Content-Type: application/json; charset=UTF-8

## 请求参数

**Request Header**

|参数|是否必选|参数类型|描述|
|:-----------|:---|:-----|:---------------------------------------------------------------------------------------------------------------------|
|Content-Type|是|String|取值为：application/json; charset=UTF-8|
|PayMercAuth|是|String|取值为：[PayMercAuth](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-model#paymercauth)的JSON字符串|

**Request Body**

|参数|是否必选|类型|说明|
|:----------------|:---|:-----|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|mercOrderNo|否|String|商户订单号，由商户自己生成，商户需保证订单信息唯一性。最大长度46。sysTransOrderNo与该参数必选其一。|
|sysTransOrderNo|否|String|华为支付系统订单号。mercOrderNo与该参数必选其一，同时传递则以sysTransOrderNo为准。|
|mercRefundOrderNo|是|String|商户退款订单号，商户需要保证字段唯一性。最大长度64。 相同的退款订单号多次请求只退一笔。 针对同一笔退款请求，如果失败或异常，重试时保证此参数不变，防止重复退款。|
|reason|否|String|退款原因，账单详情中显示。最大长度为256。|
|callbackUrl|是|String|回调通知地址，通知URL必须为外网环境可直接访问的URL，要求为https地址。具体要求参考[通知回调接口说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-rest-overview#通知回调接口说明)。最大长度为512。|
|refundAmount|否|Long|退款总金额。订单需要退款的金额，该金额不能大于订单金额，单位：分。 **说明：** 如果正向交易使用了营销，该退款金额包含营销金额，华为支付会按业务规则分配营销和买家自有资金分别退多少，默认按比例退款。如不填则默认全额退款。|
|payload|否|String|商户预留信息，在查询和回调通知时会原样返回。最大长度255。|

## 请求示例

```json
POST /api/v1/aggr/transactions/refunds HTTP/1.1
Content-Type: application/json;charset=UTF-8
PayMercAuth: {"callerId":"10132120***","traceId":"202305151442062977847","time":1684132926969,"authId":"120291744647139***","headerSign":"BpOBa8o+gJnKG+vHVI7u********************mVuKDV8iPqNJ+Y8b4XDpSi3FHgjozsWH+uLoTSIg=","bodySign":"lHjrX3dv44zyfu+PO1G+oa9tJi2********************EatA8QTjLPsSPKfM="}
Accept: application/json
{
  "mercOrderNo": "czl00120240705***",
  "mercRefundOrderNo": "czl0012024070914***",
  "reason": "123456",
  "callbackUrl": "https://www.xxxxxx.com/hw/pay/callback",
  "refundAmount": 2,
  "payload": "example-payload"
}
```

## 响应参数

**Response Header**

|参数|是否必选|参数类型|描述|
|:-----------|:---|:-----|:----------------------------------|
|Content-Type|是|String|取值为：application/json; charset=UTF-8|

**Response Body**

|参数|是否必选|参数类型|描述|
|:----------------|:---|:-----|:---------------------------------------------------------------------------------------------------------------|
|resultCode|是|String|结果码，"000000"表示成功，其他表示失败。|
|resultDesc|是|String|结果描述。|
|subCode|否|String|业务错误码。|
|subDesc|否|String|业务错误描述信息。|
|sign|是|String|签名值。用于开发者对响应报文进行防篡改验证。|
|mercRefundOrderNo|是|String|商户退款订单号。最大长度64。|
|sysRefundOrderNo|是|String|华为支付退款订单号。|
|sysTransOrderNo|是|String|华为支付系统订单号。|
|mercOrderNo|是|String|商户订单号，由商户自己生成，商户需保证订单信息唯一性。最大长度46。|
|refundAmount|是|Long|退款总金额。订单需要退款的金额，该金额不能大于订单金额，单位：分。 **说明：** 如果正向交易使用了营销，该退款金额包含营销金额，华为支付会按业务规则分配营销和买家自有资金分别退多少，默认按比例退款。如不填则默认全额退款。|
|payerRefundAmount|否|Long|退款给用户的金额，单位：分。|

## 响应示例

```json
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resultCode": "000000",
  "resultDesc": "Success.",
  "sign": "MEUCIEhVD6FuZ5iIh41AScvWO********************uZCdiWp/WVE8SoZOSXWMI0JGRXrj0=",
  "mercRefundOrderNo": "czl0012024070914***",
  "sysRefundOrderNo": "12407030900270084914518***",
  "sysTransOrderNo": "12407030857530004914518***",
  "mercOrderNo": "czl00120240705***",
  "refundAmount": 2,
  "payerRefundAmount": 2
}
```

## 错误码

**resultCode** 非400000的错误码请查看[公共错误码说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-error-code-rest#公共错误码说明)。

|**返回码**|**错误码**|**错误描述**|解决方案|
|:------|:------------------------------|:------------|:------------------------------------------------------------------------------------|
|400000|UNKNOW_ERROR|服务暂不可用，请稍后重试|稍后重试。|
|400000|INVALID_ARGUMENTS|参数不合法|检查请求参数。|
|400000|INVALID_MERCNO|无效商户号|检查入参商户号是否正确。|
|400000|REJECTED_BY_RISK_CONTROL|风控拒绝|咨询华为支付团队，[在线提单](https://developer.huawei.com/consumer/cn/support/feedback/#/)。|
|400000|NO_MATCH_MATCHING_PRODUCT|未匹配到商户产品|检查商户产品是否配置正确。|
|400000|CHECK_ORDER_STATUS|订单状态异常|请检查是否使用相同订单重复下单。|
|400000|BANK_CARD_NOT_SUPPORT|银行卡不支持|更换其他银行卡重试。|
|400000|CHECK_ACCOUNT_STATUS|支付账号异常|请检查支付账号状态。|
|400000|CHECK_MERC_STATUS|商户状态异常|请检查商户状态是否正常。|
|400000|MERC_NOT_SUPPORT_REFUND|商户不支持退款|请检查商户是否具有退款权限。|
|400000|CHECK_AMOUNT_INVALID|金额校验失败。|检查传入金额是否合法|
|400000|CHECK_ACCOUNT_BALANCE|账户余额不足。|查看商户账户余额|
|400000|RETRY_TOO_MANY|重试次数超限，请换单重试。|使用新的订单号重新请求|
|400000|ORDER_CONCURRENT_ERROR|订单退款并发错误。|1. 一笔普通收单多次退款，时间间隔要在1分钟以上 2. 合单多笔子单退款，时间间隔要在1分钟以上|
|400000|CUST_NOT_EXIST|用户不存在或已销户。|检查退款用户|
|400000|NOT_IN_VALIDITY_PERIOD|不在有效期内。|检查退款订单是否已过期|
|400000|NOT_SUPPORTED_OPERATION|不支持的操作。|请确认操作是否允许，如无法确认可[在线提单](https://developer.huawei.com/consumer/cn/support/feedback/#/)。|
|400000|RESTRICTED_USER_ACCOUNT|用户账户受限|请确认用户账户状态是否正常。|
|400000|RESTRICTED_USER_TRANSACTION|用户交易受限|请确认用户状态是否正常。|
|400000|RESTRICTED_MERCHANT_TRANSACTION|商户交易受限|请检查商户支付账号状态是否正常。|