文档首页›虚拟银行›开发文档›API 列表›异步通知›入金异步通知

入金异步通知

更新时间： 2026年9月29日 05:43

接口说明

入金回调 属于虚拟银行异步通知。商户收到通知后应先验签，再处理业务并按要求返回成功标识。

接口名称	入金回调
请求方式	平台异步通知
通知地址	由商户在平台配置，平台按配置地址回调
通知方式	POST / application/json
签名方式	MD5 ，按签名规则说明生成或校验 sign
结果判定	先判断公共返回 code，成功后验签并解析 bizData；最终业务状态以业务字段、查询接口或异步通知为准

流程图

处理要点：

• 请求前先将业务字段组装为 bizData JSON 字符串，再和公共参数一起参与签名。

• 响应或通知包含 sign 时，应先按签名规则验签，再解析 bizData。

• code=000000 表示接口请求处理成功，不等同于所有异步业务流程最终完成。

• 异步通知处理成功后应返回 SUCCESS 固定字符串；未返回或返回错误时，平台会按通知规则重试。

请求参数

应用场景

• 虚拟银行账户外部入金的时候会触发回调，系统将会推送入金记录

• 需要下游提供入金回调的异步通知地址给运营配置

• 需返回SUCCESS固定字符串作为接收成功的响应

• 网关检测到 SUCCESS 响应后，将终止后续所有通知重试；若未返回该响应或响应内容错误，网关将按预设规则重试通知，最多推送 6 次。

• 请做好接口幂等性处理

• 内部资金的流转没有异步通知例如分账，退款

字段名	变量名	必填	类型	示例值	描述
订单号	orderNo	是	String	AT12123123	平台订单号
账户号	acctNo	是	String	AC123123	登记薄账户号
状态	state	是	Number	INIT	状态INIT：初始化PROCESSING：处理中SUCCESS：成功FAIL：失败
金额	amount	是	Long	100	提现金额(单位分，保留整数)示例：100 表示 1元
手续费	mchFee	是	Long	100	手续费(单位分，保留整数)示例：100 表示 1元
手续费扣费方式	feeType	是	String	ACCOUNT	续费扣费方式ORDER- 订单内扣；ACCOUNT - 外扣
入账金额	realAmount	是	Long	100	入账金额(单位分，保留整数)示例：100 表示 1元如果手续费为ACCOUNT外扣模式则金额和入账金额保持一致，手续费从外部扣除如果手续费为ORDER内扣模式则金额和入账金额不一致，手续费从金额中扣除
描述	note	否	String	描述	当有报错返回时候会返回报错信息
出金账户名称	payerName	是	String	AT12123123	出金账户名称
出金银行账户号	payerBankAcctNo	是	String	SA12312312	出金银行账户号

请求示例

以下示例默认使用 MD5 作为演示模式。签名时先将公共参数按字段名升序排序并拼接为 key=value&key=value，再在原串末尾追加 &appSecret=... 后计算 MD5；生成 sign 后，实际请求体中不要传 appSecret。本页请求示例依赖签名规则说明中的公共签名实现。

异步通知由平台发起，商户无需主动调用。

异步通知由平台发起，商户无需主动调用。

复用签名规则说明中的 genSign / verifySign 通用方法。

Map<String, Object> biz = new LinkedHashMap<>();
biz.put("orderNo", "ORDERNO<DEMO_ID>");
biz.put("String", "StringValue");
biz.put("AT12123123", "AT12123123Value");
biz.put("acctNo", "ACCTNO<DEMO_ID>");
biz.put("AC123123", "AC123123Value");
biz.put("state", "stateValue");
biz.put("Number", "NumberValue");
biz.put("INIT", "INITValue");
biz.put("amount", 100);
biz.put("Long", "LongValue");

Map<String, String> req = new LinkedHashMap<>();
req.put("apiKey", "<API_KEY>");
req.put("bizData", mapper.writeValueAsString(biz));
req.put("reqId", "NOTIFY" + System.currentTimeMillis());
req.put("reqTime", "<DEMO_ID>");
req.put("signType", "MD5");
req.put("version", "1.0");
req.put("sign", SignDemo.genSign(req, "MD5"));

PHP 示例中的 SignDemo 类不在本页定义，推荐来自统一签名类实例。

<?php
require_once __DIR__ . '/SignDemo.php';
$demo = new SignDemo();

$biz = [
    'orderNo' => 'ORDERNO<DEMO_ID>',
    'String' => 'StringValue',
    'AT12123123' => 'AT12123123Value',
    'acctNo' => 'ACCTNO<DEMO_ID>',
    'AC123123' => 'AC123123Value',
    'state' => 'stateValue',
    'Number' => 'NumberValue',
    'INIT' => 'INITValue',
    'amount' => 100,
    'Long' => 'LongValue',
];

$req = [
    'apiKey' => '<API_KEY>',
    'bizData' => json_encode($biz, JSON_UNESCAPED_UNICODE),
    'reqId' => 'NOTIFY' . time(),
    'reqTime' => '<DEMO_ID>',
    'signType' => 'MD5',
    'version' => '1.0',
];
$req['sign'] = $demo->genSign($req);

biz = {
    'orderNo': 'ORDERNO<DEMO_ID>',
    'String': 'StringValue',
    'AT12123123': 'AT12123123Value',
    'acctNo': 'ACCTNO<DEMO_ID>',
    'AC123123': 'AC123123Value',
    'state': 'stateValue',
    'Number': 'NumberValue',
    'INIT': 'INITValue',
    'amount': 100,
    'Long': 'LongValue',
}
req = {
    'apiKey': '<API_KEY>',
    'bizData': json.dumps(biz, ensure_ascii=False),
    'reqId': f'NOTIFY{int(time.time())}',
    'reqTime': '<DEMO_ID>',
    'signType': 'MD5',
    'version': '1.0',
}
req['sign'] = gen_sign(req, 'MD5')

const biz = {
  "orderNo": "ORDERNO<DEMO_ID>",
  "String": "StringValue",
  "AT12123123": "AT12123123Value",
  "acctNo": "ACCTNO<DEMO_ID>",
  "AC123123": "AC123123Value",
  "state": "stateValue",
  "Number": "NumberValue",
  "INIT": "INITValue",
  "amount": 100,
  "Long": "LongValue",
};
const req = {
  apiKey: '<CONFIGURED_VALUE>',
  bizData: JSON.stringify(biz),
  reqId: 'NOTIFY' + Date.now(),
  reqTime: '<DEMO_ID>',
  signType: 'MD5',
  version: '1.0',
};
req.sign = genSign(req, 'MD5');

响应示例

{
  "code": "000000",
  "msg": "请求成功",
  "sign": "mock-sign-value",
  "signType": "MD5",
  "timestamp": "<DEMO_ID>",
  "bizData": "{}"
}

结果判定口径

• 公共状态：code=000000 表示接口请求处理成功；非 000000 时按 msg 排查签名、参数或业务校验问题。

• 业务状态：如响应 bizData 内存在 state、status、result、batchNo、orderNo、reqNo 等字段，应以对应业务字段作为后续处理依据。

• 验签顺序：响应或通知中返回 sign 时，先验签再解析和入库 bizData。

• 异步场景：同步成功通常只代表请求受理，最终结果以回调通知或查询接口为准。

错误处理

• 签名失败：核对 apiKey、signType、密钥、参数排序、bizData 字符串化方式和字符编码。

• 参数错误：按本页请求参数表检查必填项、枚举值、金额单位、时间格式和单号唯一性。

• 业务失败：读取 code、msg 和 bizData 内业务字段，按接口语义修正后再重试。

• 网络超时或响应未知：不要直接判定业务失败，使用查询接口或平台后台核实后再处理。

接入注意事项

• reqId 应保证每次请求唯一，便于排查和幂等处理。

• bizData 必须作为 JSON 字符串参与签名；实际请求体中不要传 appSecret。

• 生产环境与沙箱环境的应用、密钥和数据通常相互隔离，联调时请确认使用对应环境配置。

• 金额字段如无特殊说明，按源文档口径以“分”为单位。

• 字段枚举、状态流转和条件必填规则以本页参数说明为准；源文档未说明的场景请联系平台确认。