微信确认收款与转账接口实战

前言

微信支付生态中，收款与转账是企业资金流转的核心环节。但官方企业微信支付接口门槛高、审核周期长，对于小团队、SCRM系统、任务奖励平台来说往往难以快速落地。基于 iPad 协议的个人微信 API 提供了另一条路径——直接对接个人微信号，实现转账确认收款的自动化处理，大幅降低人工介入成本。

一、微信转账与确认收款的业务场景

在实际业务中，"转账"和"确认收款"是两个独立的动作，却高度耦合。

转账侧：企业将奖励、佣金、退款等资金发送到指定微信号。这一步在微信端表现为一条"转账"消息，对方在 24 小时内可以接受或拒绝。超时未操作，资金自动退回。

收款侧：接收方看到转账消息后，手动点击"确认收款"完成到账。如果接收方是自动化脚本控制的微信号（例如回收号、测试号、风控大号），就需要通过接口自动完成这一操作，而不是人工盯屏。

典型应用场景包括：

• 任务奖励平台：用户完成任务后，系统自动发红包或转账，同时需要另一个托管号自动确认收款完成对账；
• SCRM 资金管理：运营多个微信号的企业，需要在不同号之间调度资金，转账和收款全程自动化；
• 测试与对账：在沙箱环境中，发起转账后需要立即确认收款，以验证整条资金链路是否畅通；
• 代运营场景：托管他人微信号，按需确认合规转账，替代人工操作节省人力。

这些场景的共同痛点是：手动点击效率低、漏操作概率高、无法留存结构化的操作日志。

二、接口方案选型对比

在进入代码实战之前，有必要先梳理清楚各类方案的利弊，避免踩坑。

基于 微信 iPad 协议 的方案，核心优势在于它模拟的是 iPad 客户端的底层通信协议，而非网页 Hook 或 Xposed 注入，稳定性更高，也更贴近真实用户行为，触发封号风险相对较低。

WechatApi 平台正是以此协议为基础，封装了包括转账、确认收款、消息收发、群管理在内的数十个接口，开发者只需调用 HTTP POST 即可完成复杂的微信操作，无需了解协议底层细节。

三、接入前置准备

在调用转账与收款接口之前，需要完成以下准备工作：

3.1 注册并获取鉴权凭证

前往 WechatApi 控制台 注册账号，完成实名后可获得：

• VideosApi-token：请求鉴权头，所有接口调用均需携带；
• appId：设备 ID，唯一标识一个托管中的微信号实例。

每个在线的微信号对应一个 appId，如果你托管了多个号（常见于 SCRM 场景），需要在业务层维护一张 wxid → appId 的映射表。

3.2 确认设备在线

转账和收款接口依赖设备处于登录态。调用前建议先查询设备状态：

bashcurl -X POST https://api.example-domain.com/device/status \
  -H "Content-Type: application/json" \
  -H "VideosApi-token: YOUR_TOKEN_HERE" \
  -d '{
    "appId": "YOUR_APP_ID"
  }'

返回示例：

json{
  "ret": 200,
  "msg": "success",
  "data": {
    "status": "online",
    "wxid": "wxid_xxxxxxxxxxxxxx",
    "nickname": "测试账号A"
  }
}

只有 status 为 online 时，后续的转账与收款操作才能正常执行。若设备离线，需要重新扫码登录。

3.3 确认对方账号有效

转账前务必先调用"查询联系人信息"或"搜索微信号"接口，确认目标 wxid 存在且为好友关系，否则转账会直接失败，还可能产生无效的资金操作记录。

四、发起微信转账接口实战

4.1 接口调用范式

WechatApi 所有接口均遵循统一规范：

• 请求方式：HTTP POST
• 数据格式：JSON
• 鉴权方式：请求头 VideosApi-token
• 业务标识：请求体中的 appId（设备 ID）
• 返回体结构：{"ret": 200, "msg": "...", "data": {...}}

4.2 发起转账请求

以下是一个 Python 实现示例，向指定好友转账 10 元：

pythonimport requests

API_BASE = "https://api.example-domain.com"
TOKEN = "YOUR_VIDEOS_API_TOKEN"
APP_ID = "YOUR_APP_ID"

def transfer_money(to_wxid: str, amount_fen: int, remark: str = "") -> dict:
    """
    向好友发起微信转账
    :param to_wxid: 接收方微信ID
    :param amount_fen: 转账金额（单位：分）
    :param remark: 转账备注（可选）
    :return: 接口返回体
    """
    url = f"{API_BASE}/transfer/send"
    headers = {
        "Content-Type": "application/json",
        "VideosApi-token": TOKEN
    }
    payload = {
        "appId": APP_ID,
        "toWxid": to_wxid,
        "amount": amount_fen,   # 1000 = 10.00元
        "remark": remark
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=15)
    return resp.json()

# 实际调用
result = transfer_money(
    to_wxid="wxid_targetuser123",
    amount_fen=1000,
    remark="任务奖励"
)
print(result)
# 预期输出：{"ret": 200, "msg": "转账成功", "data": {"transferId": "t_abc123..."}}

4.3 转账返回体解析

成功发起后，data 中会携带一个 transferId，这是后续确认收款操作的关键凭据，务必持久化存储。

json{
  "ret": 200,
  "msg": "转账已发送，等待对方确认",
  "data": {
    "transferId": "t_202406131045_abc123",
    "toWxid": "wxid_targetuser123",
    "amount": 1000,
    "status": "pending",
    "expireAt": 1718316000
  }
}

字段说明：

• transferId：转账唯一标识，确认收款时需要用到；
• status：当前状态，pending 表示等待接收方确认；
• expireAt：过期时间戳（Unix 秒），超过此时间未确认将自动退款。

五、确认收款接口实战

5.1 使用场景说明

确认收款接口通常用于托管的接收方微信号，即你控制了收款方的微信号（也注册了对应 appId），需要在收到转账消息后自动触发确认操作，无需人工点击。

这在以下场景尤为重要：

• 多号资金调度：从 A 号转到 B 号，B 号由系统自动确认，实现无人干预的账户间转账；
• 自动化测试：测试转账链路时，收款侧自动接受，快速完成一次完整的资金闭环；
• 批量奖励发放后的对账：发出去的转账由统一的对账号自动收下，便于记录流水。

5.2 触发确认收款

pythondef confirm_receipt(receiver_app_id: str, transfer_id: str) -> dict:
    """
    控制收款方微信号确认收款
    :param receiver_app_id: 收款方设备的 appId
    :param transfer_id: 转账ID（发起方接口返回）
    :return: 接口返回体
    """
    url = f"{API_BASE}/transfer/confirm"
    headers = {
        "Content-Type": "application/json",
        "VideosApi-token": TOKEN
    }
    payload = {
        "appId": receiver_app_id,   # 注意：这里用收款方的 appId
        "transferId": transfer_id
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=15)
    return resp.json()

# 使用发起转账时拿到的 transferId
confirm_result = confirm_receipt(
    receiver_app_id="RECEIVER_APP_ID",
    transfer_id="t_202406131045_abc123"
)
print(confirm_result)

成功确认后返回：

json{
  "ret": 200,
  "msg": "确认收款成功",
  "data": {
    "transferId": "t_202406131045_abc123",
    "status": "completed",
    "confirmedAt": 1718316120,
    "actualAmount": 1000
  }
}

status 变为 completed 即代表资金已到账。

六、完整资金链路与异常处理

一个生产可用的转账确认收款流程，不能只有"正常路径"，还需要覆盖各种异常：

6.1 推荐的完整流程

发起方在线检查
    ↓
查询收款方微信号是否为好友
    ↓
调用 transfer/send → 获取 transferId
    ↓
持久化存储 transferId + expireAt
    ↓
（如果收款方也由系统控制）
调用 transfer/confirm → 确认收款
    ↓
查询 transfer/status → 验证 status=completed
    ↓
写入业务流水日志

6.2 常见错误码与处理建议

6.3 超时未确认的退款处理

转账 24 小时未被确认会自动退款到发起方。建议在业务层设置一个定时任务，在 expireAt - 1小时 时主动查询状态。若仍为 pending，可以根据业务逻辑决定是否重新转账或通知运营人工处理。

pythonimport time

def check_transfer_status(sender_app_id: str, transfer_id: str) -> str:
    url = f"{API_BASE}/transfer/status"
    headers = {
        "Content-Type": "application/json",
        "VideosApi-token": TOKEN
    }
    payload = {"appId": sender_app_id, "transferId": transfer_id}
    resp = requests.post(url, json=payload, headers=headers, timeout=10)
    data = resp.json()
    return data.get("data", {}).get("status", "unknown")

# 示例：轮询等待确认（生产中应改为消息回调，避免轮询）
for _ in range(5):
    status = check_transfer_status("SENDER_APP_ID", "t_202406131045_abc123")
    if status == "completed":
        print("收款已确认")
        break
    elif status == "refunded":
        print("已退款，需重新处理")
        break
    time.sleep(30)

七、接入 WechatApi 的进阶实践

7.1 消息回调联动

除了主动轮询，WechatApi 支持配置 Webhook 回调。当转账消息被接收方确认时，平台会主动 POST 一条事件通知到你设定的回调 URL。推荐优先使用回调模式，避免轮询带来的不必要请求开销。

回调 payload 示例：

json{
  "event": "transfer.confirmed",
  "appId": "RECEIVER_APP_ID",
  "data": {
    "transferId": "t_202406131045_abc123",
    "fromWxid": "wxid_sender",
    "amount": 1000,
    "confirmedAt": 1718316120
  }
}

在服务端接收到此事件后，立即更新数据库流水状态并触发后续业务逻辑（如积分到账、发货、通知用户等）。

7.2 多号并发转账

如果你的业务需要同时对几十、上百个用户发放奖励，建议：

1. 维护一个发送号池（多个 appId），按轮询或加权方式分配转账任务；
2. 单号单次转账有频率限制，并发过高会触发微信风控；
3. 每笔转账之间加入随机间隔（建议 2-8 秒），模拟人工操作节奏。

借助 WechatApi 的微信 SCRM 方案，可以在控制台统一管理多个账号，查看每个号的转账额度和当日操作次数，避免因超限导致的账号异常。

7.3 日志与对账

生产环境中，每笔转账操作都需要写入结构化日志，至少包含：

• 操作时间、发起方 wxid、接收方 wxid
• 金额（分）、备注
• transferId（全局唯一标识）
• 最终状态（completed / refunded / expired）

这些日志既是内部对账依据，也是出现纠纷时的操作凭证。WechatApi 控制台本身也会保留调用记录，双方对账更方便。

小结

微信确认收款与转账接口的自动化，本质是把一个需要人工盯屏点击的高频操作，转化为可编程、可审计、可监控的业务流。本文通过 WechatApi 平台，完整演示了从设备在线检查、发起转账、获取 transferId、自动确认收款到异常处理的全链路实战，关键要点如下：

• 所有请求遵循 HTTP POST + JSON + VideosApi-token 鉴权 + appId 标识设备 的统一范式；
• transferId 是连接发起转账和确认收款两个动作的核心凭据，必须持久化；
• 优先使用 Webhook 回调替代轮询，降低系统压力；
• 多号并发转账需控制频率，避免触发风控；
• 生产系统必须做完整的错误码处理和流水日志。

如需进一步了解 WechatApi 的完整能力，可参考微信二次开发文档，或直接访问 WechatApi 开发文档 查阅完整 API 参考手册。