informat.wechat 微信支付商家转账

概述

使用 informat.wechat 对象调用微信支付商家转账 API，支持发起转账、按商户单号或微信单号查询转账状态。所有方法自动使用系统配置的微信支付商户参数（商户号、AppID、API 私钥、证书序列号等），内部会自动完成 APIv3 签名。

参考 微信支付官方文档 - 商家转账。

前置条件

1. 在微信支付商户平台完成商家转账产品开通
2. 在系统后台配置微信支付参数（wechat.pay.*）
3. 在商户平台申请转账场景并获取 transferSceneId
4. 配置接口安全 IP 白名单

transfer

发起商家转账。

informat.wechat.transfer(request);

参数 request 对象字段：

字段	类型	必填	描述
outBillNo	String	是	商户单号，字母数字，最长 32 位，商户系统内唯一
transferSceneId	String	是	转账场景 ID，在商户平台申请
openid	String	是	收款用户在商户 AppID 下的 openid
transferAmount	int	是	转账金额，单位：分
transferRemark	String	是	转账备注，用户可见，UTF-8 编码，最长 32 字符
userName	String	否	收款用户真实姓名，转账金额 >= 2000 元时必填，需加密
notifyUrl	String	否	回调通知地址，公网可访问的 HTTPS 地址，不允许带参数
userRecvPerception	String	否	收款用户感知的付款原因，不传则展示场景默认值
transferSceneReportInfos	String	是	场景报告信息，JSON 数组字符串，字段因场景而异
userRecvStyleType	String	否	收款展示样式：CONFIRM_PAGE（标准确认页）或 RED_PACKET（红包，单笔不超过 200 元）

返回 Object

字段	类型	描述
outBillNo	String	商户单号
transferBillNo	String	微信转账单号
createTime	String	单据创建时间（RFC3339 格式）
state	String	单据状态，见下方状态说明
packageInfo	String	跳转确认页的 package 信息，state 为 WAIT_USER_CONFIRM 时返回

示例

const result = informat.wechat.transfer({
    outBillNo: 'BILL202605270001',
    transferSceneId: '1000',
    openid: 'o-MYE42l80oelYMDE34nYD456Xoy',
    transferAmount: 100,
    transferRemark: '新会员奖励',
    userRecvPerception: '现金奖励',
    transferSceneReportInfos: JSON.stringify([
        { info_type: '活动名称', info_content: '新会员有礼' },
        { info_type: '奖励说明', info_content: '注册会员抽奖一等奖' }
    ]),
    userRecvStyleType: 'CONFIRM_PAGE'
});
console.log(result.state, result.transferBillNo);

queryTransferByOutBillNo

根据商户单号查询转账单。

informat.wechat.queryTransferByOutBillNo(outBillNo);

参数	类型	描述
outBillNo	String	商户单号

返回 Object

字段	类型	描述
mchId	String	商户号
outBillNo	String	商户单号
transferBillNo	String	微信转账单号
appid	String	应用 ID
state	String	单据状态，见下方状态说明
transferAmount	int	转账金额（单位：分）
transferRemark	String	转账备注
failReason	String	失败原因（失败时返回）
openid	String	收款用户 openid
userName	String	收款用户姓名（加密）
createTime	String	单据创建时间（RFC3339 格式）
updateTime	String	最近一次状态变更时间（RFC3339 格式）

示例

const result = informat.wechat.queryTransferByOutBillNo('BILL202605270001');
console.log(result.state, result.transferAmount);

if (result.state === 'SUCCESS') {
    console.log('转账成功，微信单号：' + result.transferBillNo);
} else if (result.state === 'FAIL') {
    console.log('转账失败，原因：' + result.failReason);
}

queryTransferByBillNo

根据微信转账单号查询转账单。

informat.wechat.queryTransferByBillNo(transferBillNo);

参数	类型	描述
transferBillNo	String	微信转账单号

返回 Object — 返回字段与 queryTransferByOutBillNo 一致。

示例

const result = informat.wechat.queryTransferByBillNo('1330000071100999991182020050700019480001');
console.log(result.state, result.outBillNo);

转账单据状态说明

状态	说明
ACCEPTED	已受理，待用户确认
PROCESSING	转账处理中
WAIT_USER_CONFIRM	等待用户确认收款
TRANSFERING	转账中
SUCCESS	转账成功（终态）
FAIL	转账失败（终态）
CANCELING	撤销中
CANCELLED	已撤销（终态）

说明

• 只有终态（SUCCESS、FAIL、CANCELLED）的转账单不会再发生状态变更。
• 用户 24 小时内未确认收款，系统将自动关闭转账单并退回资金。
• 仅支持查询最近 30 天内的转账单，超过 30 天请通过资金账单获取。

完整业务示例

// 1. 发起转账
const transferResult = informat.wechat.transfer({
    outBillNo: 'REWARD_' + Date.now(),
    transferSceneId: '1000',
    openid: 'o-MYE42l80oelYMDE34nYD456Xoy',
    transferAmount: 5000, // 50元
    transferRemark: '活动奖励发放',
    transferSceneReportInfos: JSON.stringify([
        { info_type: '活动名称', info_content: '618大促返利' },
        { info_type: '奖励说明', info_content: '消费满500返50' }
    ])
});

console.log('转账单号：' + transferResult.transferBillNo);
console.log('状态：' + transferResult.state);

// 2. 查询转账结果
const queryResult = informat.wechat.queryTransferByOutBillNo(transferResult.outBillNo);
if (queryResult.state === 'SUCCESS') {
    console.log('转账成功');
} else if (queryResult.state === 'FAIL') {
    console.log('转账失败：' + queryResult.failReason);
} else {
    console.log('转账处理中，当前状态：' + queryResult.state);
}