# 申请退款

#### 功能介绍

开发者可以调用该接口申请已交易订单退款。退款规则如下：

1.  不支持对同一笔交易单进行并发退款。
    
    *   一笔普通收单多次退款，时间间隔要在1分钟以上。
    *   合单多笔子单退款，时间间隔要在1分钟以上。
2.  订单退款只支持180天内的订单。
    
3.  申请退款成功不代表退款成功，退款场景是异步处理，需收到退款成功的异步回调通知才表示退款成功。
    
4.  服务商代特约商户退款，需要服务商在华为支付商户平台上申请API退款授权。
    

#### 使用场景

开发者已完成Payment Kit单次支付能力的集成，并且有成功交易的订单，可以通过该接口完成某笔订单的退款申请，退款成功后华为支付会回调退款结果给商户服务器。

#### 使用约束

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

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

#### 接口原型

*   **承载协议：** HTTPS POST
    
*   **接口方向：** 开发者服务器 -> 华为支付服务器
    
*   **接口URL：** 
    
*   **数据格式：**
    
    请求消息：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的JSON字符串 |

**Request Body**

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

#### 请求示例

```
POST /api/v1/partner/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": "",
  "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 | 商户订单号，由商户自己生成，商户需保证订单信息唯一性。最小长度为1，最大长度46。 |
| refundAmount | 是 | Long | 退款总金额。订单需要退款的金额，该金额不能大于订单金额，单位：分。 说明： 如果正向交易使用了营销，该退款金额包含营销金额，华为支付会按业务规则分配营销和买家自有资金分别退多少，默认按比例退款。如不填则默认payerRefundAmount。 |
| payerRefundAmount | 否 | Long | 退款给用户的金额，单位：分。 |

#### 响应示例

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

#### 错误码

**resultCode**非400000的错误码请查看公共错误码说明。

| 返回码 | 错误码 | 错误描述 | 解决方案 |
| --- | --- | --- | --- |
| 400000 | UNKNOW_ERROR | 服务暂不可用，请稍后重试 | 稍后重试。 |
| 400000 | INVALID_ARGUMENTS | 参数不合法 | 检查请求参数。 |
| 400000 | INVALID_MERCNO | 无效商户号 | 检查入参商户号是否正确。 |
| 400000 | REJECTED_BY_RISK_CONTROL | 风控拒绝 | 咨询华为支付团队，在线提单。 |
| 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 | OPERATION_NOT_AUTHORIZED | 操作未授权 | 检查是否已申请API退款授权。 |
| 400000 | CUST_NOT_EXIST | 用户不存在或已销户 | 检查退款用户。 |
| 400000 | NOT_IN_VALIDITY_PERIOD | 不在有效期内 | 检查退款订单是否已过期。 |
| 400000 | NOT_SUPPORTED_OPERATION | 不支持的操作 | 请确认操作是否允许，如无法确认可在线提单。 |
| 400000 | RESTRICTED_USER_ACCOUNT | 用户账户受限 | 请确认用户账户状态是否正常。 |
| 400000 | RESTRICTED_USER_TRANSACTION | 用户交易受限 | 请确认用户状态是否正常。 |
| 400000 | RESTRICTED_MERCHANT_TRANSACTION | 商户交易受限 | 请检查商户支付账号状态是否正常。 |