Documentation Index
Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
选择集成路线
开始集成前，先选择一条路径。两条路径最终都需要完成沙盒测试，并将验收材料提交给 Waffo 技术对接群确认。
API integration
适合已有自建收银台、需要完全控制服务端支付流程，或希望按 API Reference 手工接入的团队。
选择产品方案
一次性支付适合单次收款订单；订阅支付适合周期扣款场景。
完成额外支付配置
如需 Apple Pay 或 Google Pay，完成 沙盒与测试 中的额外测试和配置。 提交验收结果
在沙盒环境完成测试，下载并填写验收用例模板，然后将验收结果提交给 Waffo 技术对接群。
安装 waffo-integrate
运行 npx @waffo/waffo-integrate。
触发集成
在 Claude Code 或 Cursor 中触发 Waffo 集成。
回答业务问题
回答 AI 提出的业务问题，例如产品类型、退款、订阅、Webhook 是否需要接入。
审核代码和测试报告
AI 会生成代码、运行集成测试，并输出测试报告。
提交测试报告
将测试报告提交给 Waffo 技术对接群确认。
推荐：使用 AI 集成工具（waffo-integrate）
waffo-integrate 是 Waffo 官方的 AI 集成 Skill，通过交互式向导自动生成生产级代码，比手动集成快 33%，成功率 100%。
npx @waffo/waffo-integrate
- 输入
integrate waffo 或 接入waffo
- Skill 会引导你完成：选择功能（支付/退款/订阅/Webhook）→ 检测语言 → 生成代码 → 运行验证测试
支持的语言和功能
| 语言 | SDK | 框架 |
|---|
| Node.js | @waffo/waffo-node | Express, NestJS, Fastify |
| Java | com.waffo:waffo-java | Spring Boot |
| Go | github.com/waffo-com/waffo-go | Gin, Echo, Fiber, Chi |
| 指标 | 使用 Skill | 手动集成 |
|---|
| 通过率 | 100%（16/16 断言） | 75%（12/16） |
| 集成时间 | 约 128 秒 | 约 192 秒 |
| 内置 13 条 API 规则 | 自动防错（字段名、枚举值、必填项） | 需要自行查阅文档 |
手动集成
如果不使用 AI 工具，可以按以下步骤手动集成。
前置条件
- Waffo 商户账号
- API Key（从 Dashboard 获取）
- RSA 密钥对（参见 认证与签名）
安装 SDK
npm install @waffo/waffo-node
初始化客户端
import { Waffo, Environment } from '@waffo/waffo-node';
const waffo = new Waffo({
apiKey: process.env.WAFFO_API_KEY,
privateKey: process.env.WAFFO_PRIVATE_KEY,
waffoPublicKey: process.env.WAFFO_PUBLIC_KEY,
merchantId: process.env.WAFFO_MERCHANT_ID,
environment: Environment.SANDBOX,
});
创建一笔支付
import { randomUUID } from 'crypto';
const paymentRequestId = randomUUID().replace(/-/g, '');
const response = await waffo.order().create({
paymentRequestId,
merchantOrderId: `ORDER_${Date.now()}`,
orderCurrency: 'HKD',
orderAmount: '100.00',
orderDescription: 'Test Payment',
notifyUrl: 'https://your-site.com/webhook/waffo',
userInfo: {
userId: 'user_123',
userEmail: 'user@example.com',
userTerminal: 'WEB',
},
paymentInfo: { productName: 'ONE_TIME_PAYMENT' },
goodsInfo: { goodsUrl: 'https://your-site.com/product/001' },
});
if (response.isSuccess()) {
const data = response.getData();
// 将用户重定向到 Waffo 收银台
redirect(data.orderAction);
}
下一步
