切换主题
提现异步通知
概述
当虚拟银行提现进入处理中或产生最终结果时，平台会向商户配置的异步通知地址推送提现结果。收到通知后，应先校验 sign，再解析 bizData，并使用平台订单号或商户订单号进行幂等处理。
通知说明
| 项目 | 说明 |
|---|---|
| 通知名称 | 提现异步通知 |
| 通知方向 | 平台主动通知商户 |
| 通知地址 | 由商户配置，平台向配置的通知地址发送结果 |
| 通知方式 | POST / application/json |
| 签名方式 | 按 签名规则说明 校验 sign |
| 业务关联 | 订单重新结算及虚拟银行提现结果通知 |
TIP
❗ 通知回执要求 商户成功接收并处理通知后，HTTP 响应体必须返回大写纯文本 SUCCESS。平台收到 SUCCESS 后将停止后续通知；未返回、返回其他内容或请求超时时，平台将继续通知，最多通知 6 次。
TIP
💡 结果判定：外层 code=000000 表示通知报文有效，不代表提现成功。提现结果必须以 bizData.state 为准；失败原因读取 bizData.note。
通知报文示例
json
{
"bizData": "{\"acctNo\":\"VA<DEMO_ID>\",\"amount\":10,\"fee\":0,\"feeType\":\"ORDER\",\"note\":\"对方行账户状态异常[SPS]\",\"orderNo\":\"AP<DEMO_ID>\",\"outOrderNo\":\"Item<DEMO_ID>\",\"payerBankAcctNo\":\"<DEMO_ID>\",\"payerName\":\"示例企业\",\"realAmount\":0,\"state\":\"FAIL\"}",
"code": "000000",
"msg": "请求成功",
"sign": "<SIGNATURE>",
"signType": "MD5",
"timestamp": "<DEMO_ID>"
}公共通知参数
| 变量名 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| code | String | 是 | 000000 | 公共状态码，000000 表示通知报文有效 |
| msg | String | 是 | 请求成功 | 公共返回描述 |
| timestamp | String | 是 | <DEMO_ID> | 通知发送时间，格式为 yyyyMMddHHmmss |
| signType | String | 是 | MD5 | 通知签名类型 |
| sign | String | 是 | 59d710...9c028 | 通知签名值，处理业务前必须先验签 |
| bizData | String | 是 | 见示例 | 提现业务结果 JSON 字符串，验签通过后再解析 |
业务通知参数（bizData）
| 变量名 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| amount | Long | 是 | 10 | 提现金额，单位：分 |
| mchFee | Long | 是 | 0 | 手续费，单位：分 |
| feeType | String | 是 | ORDER | 手续费扣费方式：ORDER 为订单内扣，ACCOUNT 为账户外扣 |
| note | String | 否 | 对方行账户状态异常[SPS] | 渠道处理说明或失败原因 |
| orderNo | String | 是 | AP<DEMO_ID> | 平台订单号 |
| outOrderNo | String | 是 | Item<DEMO_ID> | 商户订单号 |
| payerBankAcctNo | String | 是 | <DEMO_ID> | 出金银行账户号 |
| payerAcctNo | String | 是 | VA4878787878 | 付款方账户号 |
| payerName | String | 是 | 示例企业 | 出金账户名称 |
| payeeBankAcctNo | String | 是 | <DEMO_ID> | 收款方银行卡号 |
| payeeName | String | 是 | V123123 | 收款方名称 |
| realAmount | Long | 是 | 0 | 实际到账金额，单位：分 |
| state | String | 是 | FAIL | 提现状态： INIT：初始化 PROCESSING 处理中、 SUCCESS 成功、 FAIL 失败 |
处理建议
使用通知原始字段校验 sign，验签通过前不要处理或入库 bizData。
解析 bizData，以 orderNo 或 outOrderNo 作为幂等键，防止重复通知导致重复处理。
state=PROCESSING 时保持处理中状态，等待后续通知或通过查询接口确认。
state=SUCCESS 时更新提现成功；state=FAIL 时更新提现失败并保存 note。
本示例中的 state=FAIL，失败原因为“对方行账户状态异常[SPS]”。符合重新结算条件时，可调用订单重新结算接口重试。
业务处理成功后，HTTP 响应体返回大写纯文本 SUCCESS。不要返回 JSON 包装或其他内容；平台收到 SUCCESS 后停止通知，否则最多通知 6 次。
安全与幂等
通知可能重复发送，业务处理必须具备幂等性。
建议保存通知原文、验签结果、接收时间和状态变更记录，便于审计与排查。
日志中涉及银行账号、企业名称等敏感信息时，应按生产环境安全规范脱敏。