目录

申请退款

功能介绍

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

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

    • 一笔普通收单多次退款，时间间隔要在1分钟以上。
    • 合单多笔子单退款，时间间隔要在1分钟以上。

  2. 订单退款只支持180天内的订单。

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

使用场景

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

使用约束

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

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

1. 400000 RETRY_TOO_MANY错误码场景，需要换单重试。

2. 多次部分退款场景下，每次需要换单后发起请求。

接口原型

请求参数

Request Header

参数 是否必选 参数类型 描述
Content-Type 是 String 取值为：application/json; charset=UTF-8
PayMercAuth 是 String 取值为：PayMercAuth的JSON字符串

Request Body

参数 是否必选 类型 说明
mercOrderNo 否 String 商户订单号，由商户自己生成，商户需保证订单信息唯一性。最大长度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/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 退款给用户的金额，单位：分。

响应示例

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的错误码请查看公共错误码说明。

返回码 错误码 错误描述 解决方案
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 CUST_NOT_EXIST 用户不存在或已销户。 检查退款用户
400000 NOT_IN_VALIDITY_PERIOD 不在有效期内。 检查退款订单是否已过期
400000 NOT_SUPPORTED_OPERATION 不支持的操作。 请确认操作是否允许，如无法确认可在线提单。
400000 RESTRICTED_USER_ACCOUNT 用户账户受限 请确认用户账户状态是否正常。
400000 RESTRICTED_USER_TRANSACTION 用户交易受限 请确认用户状态是否正常。
400000 RESTRICTED_MERCHANT_TRANSACTION 商户交易受限 请检查商户支付账号状态是否正常。