换单重试,视为新的业务订单,需开发者自行将新的业务订单关联业务原订单。接口重入规则说明如下(供参考):
重入判定字段 | 支持原单重入场景 | 建议换单重试场景 |
|---|---|---|
商户订单号 (mercOrderNo) |
| 代扣请求成功,代扣订单查询或代扣回调通知扣款状态为TRX_FAILED,则订单进入失败终态。如需重新扣款时,需要换单重试。 |
承载协议 | HTTPS POST |
|---|---|
接口方向 | 开发者服务器-> 华为支付服务器 |
接口URL | https://petalpay-developer.cloud.huawei.com.cn/api/v1/aggr/transactions/withhold |
数据格式 | 请求消息:Content-Type: application/json 响应消息:Content-Type: application/json |
参数 | 是否必选 | 参数类型 | 描述 |
|---|---|---|---|
Content-Type | 是 | String | 取值为:application/json; charset=UTF-8 |
PayMercAuth | 是 | String | 取值为:PayMercAuth的JSON串 |
参数 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
appId | 是 | String | 接入方应用ID。 |
mercOrderNo | 是 | String | 商户订单号,由商户自己生成,商户需保证订单信息唯一性。最大长度46。 |
mercNo | 是 | String | 商户号。最大长度12。 |
tradeSummary | 是 | String | 交易的摘要。格式建议:“商户应用名称-商品描述”。最大长度128。 |
totalAmount | 是 | long | 订单金额,必须为大于0的整数值,单位:分。 |
currency | 否 | String | 交易币种单位,最大长度为3。
|
allocationType | 否 | String | 分账类型。
|
callbackUrl | 是 | String | 回调通知地址,通知URL必须为外网环境可直接访问的URL,要求为https地址。具体要求参考通知回调接口说明。最大长度为512。 |
payload | 否 | String | 商户预留信息,在查询和回调通知时会原样返回。最大长度255。 |
expireTime | 否 | String | 交易过期时间。此时间必须为准确的UTC时间。 格式要求:"yyyy-MM-dd'T'HH:mm:ss.SSSZ" 。 说明:
/** * 获取UTC格式的过期时间 * @param expectedExpiredTime 交易过期时间,请换算为分钟 * @return UTC时间 */ private static String getTradeExpireTime(int expectedExpiredTime) { SimpleDateFormat formater = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ"); formater.setTimeZone(TimeZone.getTimeZone("UTC")); Calendar calendar = Calendar.getInstance(); calendar.set(Calendar.MINUTE, calendar.get(Calendar.MINUTE) + expectedExpiredTime); return formater.format(calendar.getTime()); } |
contractId | 是 | String | 委托代扣协议ID,最大长度64。 |
payer | 否 | 用户支付时客户端信息。 |
POST /api/v1/aggr/transactions/withhold
Content-Type: application/json;charset=UTF-8
PayMercAuth: {"callerId":"10132120***","traceId":"202305151026422776499","time":1684117602555,"authId":"120291744647139***","headerSign":"u+H1Oe3fXV9mGCES89XA7tSjp8+TELYgG4bKyECwrVGwwExHtdWTnKc4WvEpfjLzpzKE2/+KYaq1jD********************rxXSeR8r6X46b7491N1jKg/lOG7eAFfwjEWJu5JyvY5KunSeE6DiKs=","bodySign":"yWDtXOBqDoItPgHmF57L6U5G7F/LhsILChu8YSpVV0HwRQCzdGAz53wDk********************xHMcUWx7N6405QrcBimTcTN7pBpFA7pvFexUasPj10iUIFeaszpiRT2aQDaqLGaxvta6J5UxIUmAp+wGdV/juGEvQ="}
Accept: application/json
{
"appId": "101831***",
"contractId": "2024070914615843071097***",
"mercNo": "101723200xxx",
"mercOrderNo": "czl00120230901085853",
"allocationType": "DELAY_ORDER_ALLOCATION",
"callbackUrl": "https://www.xxxxxx.com/hw/pay/callback/callback",
"currency": "CNY",
"totalAmount": 2,
"tradeSummary": "杂志报刊"
} 参数 | 是否必选 | 参数类型 | 描述 |
|---|---|---|---|
Content-Type | 是 | String | 取值为:application/json; charset=UTF-8 |
参数 | 是否必选 | 参数类型 | 描述 |
|---|---|---|---|
resultCode | 是 | String | 返回码,"000000"表示成功,其他表示见错误码 |
resultDesc | 是 | String | 结果描述 |
subCode | 否 | String | 业务错误码 |
subDesc | 否 | String | 业务错误描述信息 |
sign | 是 | String | 签名值 |
sysTransOrderNo | 是 | String | 华为支付系统订单号 |
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"resultCode": "000000",
"resultDesc": "Success.",
"sign": "MEQCIEIWzdpziRyTi8vhwWHFuDdxfsiw********************r0YAMabeCgTDG77e+2XJItvq/ZkIcCN5/B20pQ==",
"sysTransOrderNo": "12407030857530004914518***"
} (resultCode非400000的错误码请看公共错误码说明)
resultCode | resultDesc | subCode | subDesc |
|---|---|---|---|
400000 | 业务处理失败 | UNKNOW_ERROR | 服务暂不可用, 请稍后重试 |
400000 | 业务处理失败 | CUST_NOT_EXIST | 用户不存在或已销户 |
400000 | 业务处理失败 | INVALID_ARGUMENTS | 参数不合法 |
400000 | 业务处理失败 | INVALID_MERC_NO | 无效商户号 |
400000 | 业务处理失败 | CHECK_TRANSACTION_ORDER_STATUS | 交易订单状态异常 |
400000 | 业务处理失败 | CHECK_MERC_STATUS | 商户状态异常 |
400000 | 业务处理失败 | MERC_NOT_SUPPORT_ALLOCATION | 商户不支持分账 |
400000 | 业务处理失败 | CHECK_ACCOUNT_STATUS | 用户状态异常 |
400000 | 业务处理失败 | INVALID_PAYMENT_TYPE | 用户无有效支付方式 |
400000 | 业务处理失败 | WITHHOLD_OVER_TIMES | 代扣次数超限 |
400000 | 业务处理失败 | INVALID_APPID | appId不匹配 |