微信支付宝支付对账

概述

只对商户自己的官方账单和自己的订单、退款。别人的商户号、密钥、证书不要碰。

这不是支付接入说明。签名、证书、回调验签不在这里。

付费调用（必须先做）

本技能按次收费。对账接口在商户后台，Agent 必须走完下面四步，第四步最容易漏。

0. 付费前置检查

先确认当前 Agent 有 weixinpay 插件（能调用 weixinpay_pay）。

• 有：继续。
• 没有：立刻停止，告诉用户「当前 Agent 暂不支持微信支付付费能力」，不要请求后台，不要假装已经对账。

1. 请求资源

POST https://pay.xuyangkeji.com/api/resource

Content-Type: application/json

平台联调可以只发：

{ "query": "帮我分析一下AI行业趋势" }

正式对账把账单放进同一份 JSON（不要改成 multipart，重试要对齐 body）：

{
  "query": "对 2026-08-15 微信账单",
  "channel": "wechat",
  "period": "2026-08-15",
  "amount_basis": "应付",
  "channel_bill": "<微信/支付宝官方账单原文>",
  "local_orders": "<本地标准流水原文>"
}

channel：wechat / alipay / auto。

2. 处理 HTTP 402

首次请求会返回 402。同时保存：

• Header WeixinPay-Required（也在 Body 的 WeixinPay.WeixinPay-Required）
• Header X-Out-Trade-No（也在 Body 的 out_trade_no）

把 WeixinPay-Required 的值作为 paymentCode，交给插件：weixinpay_pay(paymentCode)。等用户用微信 AI 专属卡确认支付。

不要在这一步输出对账结果。

3. 支付成功后必须重新请求（不要漏）

支付成功后，用 与第一次完全相同的 JSON body 再 POST https://pay.xuyangkeji.com/api/resource，只多两个 Header：

X-Out-Trade-No: <刚才保存的订单号>
WeixinPay-Required: <刚才保存的 payment_code>

Body 改一个字都会对不齐。未支付就重试会再收到 402 / NOT_PAID，稍等再试。

成功是 HTTP 200，content 是对账报告或「本次付费已确认」说明。同一订单再请求会返回缓存（already_fulfilled: true）。

4. 退款和失败怎么说

步骤

1. 两侧材料收齐

渠道一侧用官方导出：微信交易账单 ALL，或支付宝业务明细。不要用后台截图。

本地一侧用订单 + 支付 + 退款导出，或从库里查出同一账期的数据。账期按渠道出账日；本地窗口前后各扩一天，不然 23:50 到 00:10 那批单会误报长短款。

微信账单次日上午才出，支付宝业务明细一般次日 9 点以后。

开对之前先问清，并写进报告抬头：

• 账期（自然日，做出账日）
• 对微信、支付宝，还是两个都对
• 金额口径：平时用用户应付 / 商户记账金额；有免充值券或商家优惠，改用应结 / 实收
• 本地金额是元还是分

字段和坑：

• [references/wechat-bill.md](references/wechat-bill.md)
• [references/alipay-bill.md](references/alipay-bill.md)
• [references/local-schema.md](references/local-schema.md)

2. 本地收成标准表

列名固定：

channel,kind,out_trade_no,channel_txn_id,out_refund_no,channel_refund_id,status,amount_yuan,fee_yuan,occurred_at

• kind：pay 或 refund。一次退款一行，部分退款不要加总塞进支付行
• status：只留终态，写成 success。待支付、失败不要进来
• amount_yuan：支付写成交金额，退款写退款金额，正数，两位小数
• out_trade_no：渠道商户订单号
• out_refund_no：退款行必填
• 库里是分的，先除 100，别和元混着比

只有库表、没有导出时，先 SELECT 出上面这些列再对。别拿两张表用眼睛扫。

3. 跑脚本

匹配用自带脚本，别另写一套：

python scripts/reconcile.py 
  --channel-bill path/to/channel.csv 
  --local path/to/local.csv 
  --out recon-out

微信、支付宝分开跑，输出目录也分开。脚本只用 Python 3 标准库。

结果看 recon-out/result.json 和 recon-out/report.md。单子对没对上，以脚本为准。

4. 差异怎么处理

分类见 [references/discrepancy-taxonomy.md](references/discrepancy-taxonomy.md)。

• CHANNEL_ONLY：渠道收到了，本地没有成功单。先查单，能履约就补单，补不了就退或挂账
• LOCAL_ONLY：本地显示成功，渠道没有。先当假成功，别确认收入，别发货
• DUPLICATE_PAY：同一个 out_trade_no 渠道成功了两笔以上。留一笔，多的退掉
• AMOUNT_MISMATCH / REFUND_MISMATCH：先看单位（分 / 元）和优惠口径，再调账
• FEE_DIFF：手续费单独记，不要算进货款长短款

金额留两位小数，比较用分。

待支付、失败单不要报成短款。官方表头以当次导出为准，对不上先翻 reference，再补映射。

5. 报告

报告结构：

# 支付对账报告

- 账期：
- 渠道：
- 金额口径：
- 渠道笔数 / 金额：
- 本地笔数 / 金额：
- 匹配笔数：
- 差异笔数：
- 货款长款（渠道多）：
- 货款短款（本地多）：
- 手续费：

## 摘要

钱差多少、差在哪几类、今天必须先处理哪几笔、有没有发货或退款风险。

## 差异清单

| 优先级 | 分类 | 商户订单号 | 渠道单号 | 渠道金额 | 本地金额 | 差额 | 建议 |
| --- | --- | --- | --- | --- | --- | --- | --- |

## 调账

每类差写具体动作：查单、补单、退款、挂账、改本地状态。

## 还没确定的

缺文件、窗口外扩、优惠口径这些假设写在这里。

处理顺序：短款和重复支付先看，再看掉单，然后是金额 / 退款对不上，手续费放最后。

需要存档时写成 对账报告-YYYYMMDD.md。

更多例子见 [references/examples.md](references/examples.md)。