哈喽，大家好我是阿星很多独立开发者第一次接wx支f，会先被各种文档绕晕。所以这篇教程只做一件事：在已有 Web 项目里，通过wx支f Skill 和一段简版提示词，让编码 Agent 完成普通商户 Native APIv3 接入，并真实跑通一笔 1 分钱支f。 
一、先搞清楚：wx支f Skill 是什么
先推荐大家装一下skills，wx支f Skill 是wx支f提供给 AI IDE / 编码 Agent 的专业知识包。它不是 SDK，也不会代替商户收款。
它主要解决四个问题：
- 根据业务场景选择 Native、JSAPI、H5、小cx等产品。
- 从同步到本地的wx支f官方知识库检索接口和示例。
- 检查签名、回调、金额、幂等和资金链路中的接入质量问题。
- 根据错误码、Request-ID、支f单号进行答疑和排障。
安装 Skill 后，键技术规则会先从官方知识库检索，而不是凭记忆生成。 
安装 Skill
在项目根目录执行：
# 安装wx支f官方接入 Skillnpx skills add https://github.com/wechatpay-apiv3/wechatpay-skills --yes
安装后，在 Agent 对话中输入“我要接入普通商户 Native 支f”。如果工具提示使用 wechatpay-payment-integration，说明 Skill 已经生效。
二、准备工作
普通商户 Native APIv3 最小接入需要以下内容：
| 参数 | 作用 | 获取位置 |
| AppID | 标识已认证的小cx、公众号或移动应用 | wx公众平台或开放平台 |
| 商户号 mchid | 标识wx支f商户 | 商户平台“账户中心 → 商户信息” |
| APIv3 密钥 | 解密支f回调等内容 |
商户平台“账户中心 → API安全” |
| 商户 API 私钥 | 商户请求签名 |
申请商户 API 证书后生成的 apiclient_key.pem |
| 商户证书序列号 | 请求头中的商户证书标识 | 从 apiclient_cert.pem 读取 |
| wx支f公钥及公钥 ID | 验证wx支f应答和回调签名 | 商户平台“账户中心 → API安全” |
| HTTPS 回调地址 | 接收支f成功通知 | 正式域名或本地 HTTPS 隧道 |
1. 查询 AppID 是否与商户号关联
登录wx支f商户平台，进入：
产品中心 → AppID账号管理 → 我关联的AppID账号
图源：wx支f官方《管理商户号绑定的APPID账号》文档。
Web Native 支f可以填写已认证的小cx、公众号或移动应用 AppID，但这个 AppID 必须与当前商户号有效绑定。说白了就是那个小cx的主体和你的支f主体是一个主体，否则不行。
如果使用小cx AppID，可在wx公众平台进入：
开发与服务 → 开发管理 → 开发设置 → AppID（小cxID） 
图源：wx支f官方《管理商户号绑定的APPID账号》文档。
看到“已失效”“待确认”都不算完成。Native 下单时，失效绑定通常会导致 AppID 与商户号不匹配。
2. 设置 APIv3 密钥
进入：
账户中心 → 账户设置 → API安全 → 解密回调 → APIv3密钥
图源：wx支f官方《配置APIv3密钥》文档。
APIv3 密钥是 32 个字符的字符串，主要用于解密回调。设置后无法再次查看，只能重新设置，所以必须进入受控的服务端环境变量或密钥管理系统。
3. 申请商户 API 证书
同一页找到“商户API证书”，点击“申请证书”。
图源：wx支f官方《申请商户API证书》文档。
证书工具通常会生成：
- apiclient_key.pem：商户私钥，用于给 APIv3 请求签名。
- apiclient_cert.pem：商户证书，可读取商户证书序列号。
- apiclient_cert.p12：同一套证书的 P12 格式，部分旧工具或环境会使用。
4. 下载wx支f公钥
进入：
账户中心 → API安全 → wx支f公钥 
点击申请或启用公钥：
进入详情页后下载公钥，并记录对应的公钥 ID：
图源：wx支f官方《wx支f公钥》产品介绍。
一定要记住这四者的区别：
| 内容 | 谁持有 | 用途 |
| 商户私钥 | 商户 | 对商户请求签名 |
| 商户证书 | 商户 | 提供商户证书序列号 |
| wx支f公钥 | 商户下载 | 验证wx支f应答和回调 |
| APIv3 密钥 | 商户设置 | 解密支f回调等内容 |
不要把私钥粘贴到聊天、工单或公开仓库。只要私钥曾公开，应当在正式上线前重新申请商户 API 证书。
三、把这段简版提示词交给 Agent（只包demo，生产级完整在文末）
参数准备完成后，将下面整段复制给编码 Agent：
请在当前 Web 项目中接入wx支f普通商户Native APIv3，并实际跑通一笔 1 分钱支f。 先扫描项目技术栈、现有数据库、环境变量规范和测试方式，沿用当前架构。技术细节只依据wx支f官方文档；若存在 wechatpay-payment-integration Skill，先用它检索官方知识库。能从本地证书安全读取的信息直接读取，只询问缺失参数。不得把密钥、私钥、Authorization 或完整支f链接写入源码、日志、Git 或最终回复。配置服务端环境变量：APP_ID、MCH_ID、API_V3_KEY、商户证书序列号、商户私钥路径、wx支f公钥 ID、公钥路径、HTTPS 回调地址和数据库连接。必须区分：apiclient_key.pem 是商户私钥；apiclient_cert.pem 是商户证书；pub_key.pem 是wx支f公钥；APIv3 密钥是 32 字节字符串。AppID 可以是已认证的小cx、公众号或移动应用 AppID，但必须与商户号有效绑定。 只实现最小闭环：服务端固定 1 分钱商品；创建本地订单和唯一 out_trade_no；调用 /v3/pay/transactions/native；正确签名并验证wx支f应答；保存 code_url；生成QRcode支f页；实现原始请求体回调验签、APIv3 解密、金额校验和幂等更新；实现主动查单兜底和未支f关单。本地服务可以使用 HTTP，但 notify_url 必须使用公网 HTTPS 隧道。完成后验证证书、公钥和密钥配置，运行测试/类型检查/构建，实际创建订单并打开QRcode。用户扫码后，同时通过主动查单和本地数据库确认 SUCCESS，记录wx支f订单号与支f时间。最终只输出修改文件、启动命令、支f页、回调地址、验证结果和仍需人工操作的事项。不要开发管理后台、退款、分账、会员系统或生产监控；跑通后再给正式上线建议。
完整版提示词可以额外要求日志、补偿任务、对账、生产数据库、监控和上线检查；但本地第一次验证时，先把支f闭环跑通更重要。
四、Agent 实际完成的支f链路
一个正确的 Native 支f闭环通常是：
- 浏览器请求业务服务器创建订单。
- 业务服务器先写入本地订单，再调用wx支f Native 下单接口。
- wx支f创建wx侧交易记录，返回 code_url。
- 页面把 code_url 转换成QRcode。
- 用户使用wx扫码并在wx内完成付款。
- wx支f更新自己的交易状态，并通过 HTTPS 回调通知业务服务器。
- 业务服务器验签、解密、核对金额后，将本地订单更新为成功并发放业务权益。
- 如果回调延迟或丢失，业务服务器通过主动查单补偿本地状态。
五、为什么已经有商户平台，还要自建数据库
wx支f系统和你的业务数据库记录的是两套不同事实。
wx支f系统负责资金事实
- 用户是否付款。
- wx支f订单号。
- 支f金额和支f时间。
- 退款和账单。
- wx侧交易状态。
业务数据库负责业务事实
- 哪个用户购买了哪个商品。
- 商户订单号对应哪个业务对象。
- 会员、额度或商品是否已经发放。
- 同一个回调是否处理过。
- 客服、售后和财务如何关联这笔支f。
商户平台显示“支f成功”，只代表钱已经成功支f；业务数据库显示“权益已发放”，才代表你的业务闭环完成。
六、本地为什么需要 HTTPS 隧道
本地联调需要把本地回调接口映射成公网 HTTPS 地址，例如：
# 将本地 3000 端口映射成临时公网 HTTPS 地址ngrok http 3000
将生成的 HTTPS 地址拼接回调路由，写入服务端环境变量。隧道域名变化后必须重新下单，因为每笔订单在创建时已经保存了当时的 notify_url。
七、如何验证不是“假跑通”
至少检查以下结果：
- Native 下单接口真实返回 code_url。
- 页面QRcode可以被wx“扫一扫”识别。
- 用户真实支f 1 分钱。
- wx商户平台能够查到订单。
- 主动查单返回 SUCCESS。
- 数据库保存 SUCCESS、wx支f订单号和支f时间。
- 重复查询或重复回调不会重复发放业务权益。
如果只做到QRcode出现，还不能算支f接入完成。
最后
wx支f最难的部分不是调用一个下单接口，而是理解商户身份、wx身份、四类密钥材料和两套订单账本之间的关系。
Skill 的价值，是让 Agent 每一步先查官方规则；简版提示词的价值，是给 Agent 一个明确、可验证的交付目标。
先跑通一笔真实的 1 分钱支f，再把验证过的链路扩展到你的业务，这是成本最低、也最不容易失控的接入方式Ok完整版接入提示词我放x球里了需要可自取
我是阿星更多AI应用我们下期再见
