换单重试,视为新的业务订单,需开发者自行将新的业务订单关联业务原订单。接口重入规则说明如下(供参考):
重入判定字段 | 支持原单重入场景 | 建议换单重试场景 |
|---|---|---|
商户退款订单(mercRefundOrderNo) | 发起退款请求失败,建议根据错误码(400000 RETRY_TOO_MANY错误码场景,需要换单重试)排查后,原单重试。 |
|
承载协议 | HTTPS POST |
|---|---|
接口方向 | 开发者服务器-> 华为支付服务器 |
接口URL | https://petalpay-developer.cloud.huawei.com.cn/api/v1/aggr/transactions/refunds |
数据格式 | 请求消息:Content-Type: application/json 响应消息:Content-Type: application/json |
参数 | 是否必选 | 参数类型 | 描述 |
|---|---|---|---|
Content-Type | 是 | String | 取值为:application/json; charset=UTF-8 |
PayMercAuth | 是 | String | 取值为:PayMercAuth的JSON串 |
参数 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
mercOrderNo | 否 | String | 商户订单号,由商户自己生成,商户需保证订单信息唯一性。最大长度46。sysTransOrderNo与该参数必选其一。 |
sysTransOrderNo | 否 | String | 华为支付系统订单号。mercOrderNo与该参数必选其一,同时传递则以sysTransOrderNo为准。 |
extInfo | 否 | String | 附加信息。 |
mercRefundOrderNo | 是 | String | 商户退款订单号,商户需要保证字段唯一性。最大长度64。 相同的退款订单号多次请求只退一笔。 退款失败场景,请使用原单重试。如果换单重试,将视作新的退款请求,可能出现金额校验失败的错误。 |
reason | 否 | String | 退款原因,账单详情中显示。 |
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+vHVI7u8gz7SWuCR/ZWHvhcY5a+l1C65Jl/4EECjXDdooYZoBXgpRlnzgVBpEKTD1gpsSCSV********************bfOMvDM1HkawuMmqcKq1INRFUomVuKDV8iPqNJ+Y8b4XDpSi3FHgjozsWH+uLoTSIg=","bodySign":"lHjrX3dv44zyfu+PO1G+oa9tJi2EVUOIKSzE9VHKazmLtg6APjtxoz8OTvo+B5qP0JglSpRuXnVlp0NyZGoT2c********************uyk9y3iJP6S/RAycme+ibB4qcg1Oj2KbyUUY0Fkj3zXm98TkuZ8dl65RQeBVksrKTgqn/XUqAzZpcQppxLE/2gXJHBuereHiEatA8QTjLPsSPKfM="}
Accept: application/json
{
"mercOrderNo": "qapp2820231401240800",
"extInfo": "2121312",
"mercRefundOrderNo": "202303281684132926235",
"reason": "123456",
"callbackUrl": "https://www.xxxxxx.com/hw/pay/callback",
"refundAmount": 2,
"payload": "example-payload"
} 参数 | 是否必选 | 参数类型 | 描述 |
|---|---|---|---|
Content-Type | 是 | String | 取值为:application/json; charset=UTF-8 |
参数 | 是否必选 | 参数类型 | 描述 |
|---|---|---|---|
resultCode | 是 | String | 结果码,"000000"表示成功,其他表示失败。 |
resultDesc | 是 | String | 结果描述。 |
subCode | 否 | String | 业务错误码。 |
subDesc | 否 | String | 业务错误描述信息。 |
sign | 是 | String | 签名值。用于开发者对响应报文进行防篡改验证。 |
mercRefundOrderNo | 否 | String | 商户退款订单号。 |
sysRefundOrderNo | 否 | String | 华为支付退款订单号。 |
sysTransOrderNo | 否 | String | 华为支付系统订单号。 |
mercOrderNo | 否 | String | 商户订单号。 |
refundAmount | 否 | long | 退款金额,单位:分。 |
payerRefundAmount | 否 | long | 用户退款金额,单位:分。 |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"resultCode": "000000",
"resultDesc": "Success.",
"sign": "MEUCIEhVD6FuZ5iIh41AWOScve51Hr********************bI1CdiWp/WVE8SoZOSXWMI0JGRXrj0=",
"mercRefundOrderNo": "202303281684132926235",
"sysRefundOrderNo": "1230515144208008700005826043",
"sysTransOrderNo": "12407030857530004914518***",
"mercOrderNo": "qapp2820231401240800",
"refundAmount": 2,
"payerRefundAmount": 2
} (resultCode非400000的错误码请看公共错误码说明)
resultCode | resultDesc | subCode | subDesc |
|---|---|---|---|
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 | 业务处理失败 | NOT_IN_VALIDITY_PERIOD | 不在有效期内 |
400000 | 业务处理失败 | NOT_SUPPORTED_OPERATION | 不支持的操作 |
400000 | 业务处理失败 | RESTRICTED_USER_ACCOUNT | 用户账户受限 |
400000 | 业务处理失败 | RESTRICTED_USER_TRANSACTION | 用户交易受限 |
400000 | 业务处理失败 | RESTRICTED_MERCHANT_TRANSACTION | 商户交易受限 |