codex一键接入微信支付，一个提示词搞定

先说个现象：很多独立开发者第一次接入微信支付，基本都会被官方文档绕晕——API密钥、商户证书、回调验签，光看目录就能让人想放弃。

所以这篇教程只做一件事：在已有的 Web 项目里，通过微信支付 Skill 和一段简版提示词，让编码 Agent 完成普通商户 Native APIv3 的接入，并真实跑通一笔 1 分钱的支付。

一、先搞清楚：微信支付 Skill 是什么

建议先装一下这个 skills。微信支付 Skill 是微信支付提供给 AI IDE / 编码 Agent 的专业知识包。它不是 SDK，也不会代替商户收款。

具体来说，它主要解决四个问题：

1. 根据业务场景选择 Native、JSAPI、H5、小程序等产品。
2. 从同步到本地的微信支付官方知识库检索接口和示例。
3. 检查签名、回调、金额、幂等和资金链路中的接入质量问题。
4. 根据错误码、Request-ID、支付单号进行答疑和排障。

安装 Skill 之后，关键技术规则会先从官方知识库检索，而不是凭记忆生成。

安装 Skill

在项目根目录执行：

# 安装微信支付官方接入 Skill
npx skills add https://github.com/wechatpay-apiv3/wechatpay-skills --yes

安装后，在 Agent 对话中输入“我要接入普通商户 Native 支付”。如果工具提示使用 wechatpay-payment-integration，说明 Skill 已经生效。

二、准备工作

普通商户 Native APIv3 最小接入需要以下内容：

1. 查询 AppID 是否与商户号关联

登录微信支付商户平台，进入：

产品中心 → AppID账号管理 → 我关联的AppID账号

图源：微信支付官方《管理商户号绑定的APPID账号》文档。

Web Native 支付可以填写已认证的小程序、公众号或移动应用 AppID，但这个 AppID 必须与当前商户号有效绑定。说白了，就是那个小程序的主体和你的支付主体是一个主体，否则不行。

如果使用小程序 AppID，可在微信公众平台进入：

开发与服务 → 开发管理 → 开发设置 → AppID（小程序ID）

图源：微信支付官方《管理商户号绑定的APPID账号》文档。

看到“已失效”“待确认”都不算完成。Native 下单时，失效绑定通常会导致 AppID 与商户号不匹配。

2. 设置 APIv3 密钥

进入：

账户中心 → 账户设置 → API安全 → 解密回调 → APIv3密钥

图源：微信支付官方《配置APIv3密钥》文档。

APIv3 密钥是 32 个字符的字符串，主要用于解密回调。设置后无法再次查看，只能重新设置，所以必须进入受控的服务端环境变量或密钥管理系统。

3. 申请商户 API 证书

同一页找到“商户API证书”，点击“申请证书”。

图源：微信支付官方《申请商户API证书》文档。

证书工具通常会生成：

• apiclient_key.pem：商户私钥，用于给 APIv3 请求签名。
• apiclient_cert.pem：商户证书，可读取商户证书序列号。
• apiclient_cert.p12：同一套证书的 P12 格式，部分旧工具或环境会使用。

4. 下载微信支付公钥

进入：

账户中心 → API安全 → 微信支付公钥

点击申请或启用公钥：

进入详情页后下载公钥，并记录对应的公钥 ID：

图源：微信支付官方《微信支付公钥》产品介绍。

密钥的用途容易混淆？这里需要区分清楚：

不要把私钥粘贴到聊天、工单或公开仓库。只要私钥曾公开，应当在正式上线前重新申请商户 API 证书。

三、把这段简版提示词交给 Agent（只包demo，生产级完整在文末）

参数准备完成后，将下面整段复制给编码 Agent：

请在当前 Web 项目中接入微信支付普通商户Native APIv3，并实际跑通一笔 1 分钱支付。

先扫描项目技术栈、现有数据库、环境变量规范和测试方式，沿用当前架构。技术细节只依据微信支付官方文档；
若存在 wechatpay-payment-integration Skill，先用它检索官方知识库。能从本地证书安全读取的信息直接读取，只询问缺失参数。
不得把密钥、私钥、Authorization 或完整支付链接写入源码、日志、Git 或最终回复。
配置服务端环境变量：APP_ID、MCH_ID、API_V3_KEY、商户证书序列号、商户私钥路径、微信支付公钥 ID、公钥路径、HTTPS 回调地址和数据库连接。
必须区分：
apiclient_key.pem 是商户私钥；
apiclient_cert.pem 是商户证书；
pub_key.pem 是微信支付公钥；APIv3 密钥是 32 字节字符串。
AppID 可以是已认证的小程序、公众号或移动应用 AppID，但必须与商户号有效绑定。

只实现最小闭环：
服务端固定 1 分钱商品；创建本地订单和唯一 out_trade_no；调用 /v3/pay/transactions/native；正确签名并验证微信支付应答；保存 code_url；
生成QRcode支付页；实现原始请求体回调验签、APIv3 解密、金额校验和幂等更新；实现主动查单兜底和未支付关单。
本地服务可以使用 HTTP，但 notify_url 必须使用公网 HTTPS 隧道。完成后验证证书、公钥和密钥配置，运行测试/类型检查/构建，实际创建订单并打开QRcode。
用户扫码后，同时通过主动查单和本地数据库确认 SUCCESS，记录微信支付订单号与支付时间。
最终只输出修改文件、启动命令、支付页、回调地址、验证结果和仍需人工操作的事项。
不要开发管理后台、退款、分账、会员系统或生产监控；
跑通后再给正式上线建议。

完整版提示词可以额外要求日志、补偿任务、对账、生产数据库、监控和上线检查；但本地第一次验证时，先把支付闭环跑通更重要。

四、Agent 实际完成的支付链路

一个正确的 Native 支付闭环通常是：

1. 浏览器请求业务服务器创建订单。
2. 业务服务器先写入本地订单，再调用微信支付 Native 下单接口。
3. 微信支付创建微信侧交易记录，返回 code_url。
4. 页面把 code_url 转换成二维码。
5. 用户使用微信扫码并在微信内完成付款。
6. 微信支付更新自己的交易状态，并通过 HTTPS 回调通知业务服务器。
7. 业务服务器验签、解密、核对金额后，将本地订单更新为成功并发放业务权益。
8. 如果回调延迟或丢失，业务服务器通过主动查单补偿本地状态。

五、为什么已经有商户平台，还要自建数据库

微信支付系统和你的业务数据库记录的是两套不同事实。

微信支付系统负责资金事实

• 用户是否付款。
• 微信支付订单号。
• 支付金额和支付时间。
• 退款和账单。
• 微信侧交易状态。

业务数据库负责业务事实

• 哪个用户购买了哪个商品。
• 商户订单号对应哪个业务对象。
• 会员、额度或商品是否已经发放。
• 同一个回调是否处理过。
• 客服、售后和财务如何关联这笔支付。

商户平台显示“支付成功”，只代表钱已经成功支付；业务数据库显示“权益已发放”，才代表你的业务闭环完成。

六、本地为什么需要 HTTPS 隧道

本地联调需要把本地回调接口映射成公网 HTTPS 地址，例如：

# 将本地 3000 端口映射成临时公网 HTTPS 地址
ngrok http 3000

将生成的 HTTPS 地址拼接回调路由，写入服务端环境变量。隧道域名变化后必须重新下单，因为每笔订单在创建时已经保存了当时的 notify_url。

七、如何验证不是“假跑通”

至少检查以下结果：

1. Native 下单接口真实返回 code_url。
2. 页面二维码可以被微信“扫一扫”识别。
3. 用户真实支付 1 分钱。
4. 微信商户平台能够查到订单。
5. 主动查单返回 SUCCESS。
6. 数据库保存 SUCCESS、微信支付订单号和支付时间。
7. 重复查询或重复回调不会重复发放业务权益。

如果只做到二维码出现，还不能算支付接入完成。

最后

微信支付最难的部分不是调用一个下单接口，而是理解商户身份、微信身份、四类密钥材料和两套订单账本之间的关系。

Skill 的价值，是让 Agent 每一步先查官方规则；简版提示词的价值，是给 Agent 一个明确、可验证的交付目标。

先跑通一笔真实的 1 分钱支付，再把验证过的链路扩展到你的业务，这是成本最低、也最不容易失控的接入方式。