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 最小接入需要以下内容：

参数	作用	获取位置
AppID	标识已认证的小程序、公众号或移动应用	微信公众平台或开放平台
商户号 mchid	标识微信支付商户	商户平台“账户中心 → 商户信息”
APIv3 密钥	解密支付回调等内容	商户平台“账户中心 → API安全”
商户 API 私钥	商户请求签名	申请商户 API 证书后生成的 apiclient_key.pem
商户证书序列号	请求头中的商户证书标识	从 apiclient_cert.pem 读取
微信支付公钥及公钥 ID	验证微信支付应答和回调签名	商户平台“账户中心 → API安全”
HTTPS 回调地址	接收支付成功通知	正式域名或本地 HTTPS 隧道

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：

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

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

内容	谁持有	用途
商户私钥	商户	对商户请求签名
商户证书	商户	提供商户证书序列号
微信支付公钥	商户下载	验证微信支付应答和回调
APIv3 密钥	商户设置	解密支付回调等内容

不要把私钥粘贴到聊天、工单或公开仓库。只要私钥曾公开，应当在正式上线前重新申请商户 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 分钱支付，再把验证过的链路扩展到你的业务，这是成本最低、也最不容易失控的接入方式。