1.7.0 版本支持 Node.js、Java、Go、Python 和 PHP 项目。
本页的「AI」指用 AI 编码工具完成 SDK 集成。如果你想接收 AI Agent 用稳定币支付,参见 x402 稳定币收单。
接入路线图
1
准备项目
确认项目代码已在 Codex、Claude Code 或 Cursor 中打开。
2
安装 Skill
运行
npx @waffo/waffo-integrate。3
触发 Waffo 集成
在 AI 助手中要求集成 Waffo 支付。
4
回答业务问题
选择需要的能力,例如支付、退款、订阅、商户配置查询和支付方式查询,并确认支付集成中必选 Webhook 的业务处理规则。
5
审核并生成代码
AI 工具会先展示代码预览,确认后生成 SDK 初始化、服务层、Webhook 处理和测试文件。
6
运行验证
AI 工具会运行集成测试,覆盖支付、退款、订阅和 Webhook 流程。
7
提交测试报告
将生成的测试报告发送到 Waffo 技术对接群确认。
为什么使用 waffo-integrate
安装
集成流程
1
触发 Skill
在 AI 助手中输入触发词:
集成 Waffo 支付、integrate waffo、接入waffo、waffo sdk 或 waffo payment。2
语言检测
Skill 自动检测项目语言:
package.json → Node.js,pom.xml / build.gradle → Java,go.mod → Go,pyproject.toml / requirements.txt / Pipfile / uv.lock / setup.py → Python,composer.json → PHP。3
功能选择
交互式选择需要的功能(逐个询问):支付、退款、订阅、商户配置查询、支付方式查询。支付集成中 Webhook 为必选项,需要确认对应事件的业务处理规则。选了支付会建议接退款。
4
Webhook 框架选择
选择支付或订阅时,需要为必选的 Webhook 选择 Web 框架。
5
代码预览 & 生成
Skill 先展示完整代码供审核,确认后自动生成:SDK 初始化、支付/退款/订阅服务、Webhook 处理、测试文件、
.env.example。6
集成验证
代码生成和构建通过后,Skill 按本次实际接入范围运行 Step 6 分阶段验收测试,记录执行结果和证据。必需阶段和证据完整后才生成正式测试报告;证据不足或测试失败时,输出
Verification Blocked 或 Failed Summary,不会把未完成的验证标为通过。具体验收要求和用例模板见 集成验收标准。内置 33 条代码生成规则
Skill 内置的规则自动防止常见错误。以下为部分规则摘要,表格顺序不代表上游规则编号。完整规则见references/code-generation-rules.md:
生成的代码特性
- 错误处理:区分
WaffoUnknownStatusError(可能成功)和WaffoError(客户端错误) - 安全:Webhook 签名验证、环境变量管理凭证
- 最佳实践:幂等请求 ID、服务层分离、Webhook 先注册后解析 JSON
- 测试:沙盒集成测试桩、测试卡号