跳转到主要内容

​
选择集成路线

开始集成前，先选择一条路径。两条路径最终都需要完成沙盒测试，并将验收材料提交给 Waffo 技术对接群确认。

​
API integration

适合已有自建收银台、需要完全控制服务端支付流程，或希望按 API Reference 手工接入的团队。
1

选择产品方案

一次性支付适合单次收款订单；订阅支付适合周期扣款场景。
2

接入必需 API

按 API 直连 路线图接入必需接口。
3

查看 API Reference 细节

在 API Reference 查看字段、请求、响应和签名细节。
4

完成额外支付配置

如需 Apple Pay 或 Google Pay，完成 沙盒与测试 中的额外测试和配置。
5

提交验收结果

在沙盒环境完成测试，下载并填写验收用例模板，然后将验收结果提交给 Waffo 技术对接群。

​
AI integration tool

适合希望让 AI 编码工具自动生成 SDK 接入代码、测试代码和测试报告的团队。
1

安装 waffo-integrate

运行 npx @waffo/waffo-integrate。
2

触发集成

在 Claude Code 或 Cursor 中触发 Waffo 集成。
3

回答业务问题

回答 AI 提出的业务问题，例如产品类型、退款、订阅、Webhook 是否需要接入。
4

审核代码和测试报告

AI 会生成代码、运行集成测试，并输出测试报告。
5

提交测试报告

将测试报告提交给 Waffo 技术对接群确认。

​
推荐：使用 AI 集成工具（waffo-integrate）

waffo-integrate 是 Waffo 官方的 AI 集成 Skill，通过交互式向导自动生成生产级代码，比手动集成快 33%，成功率 100%。

​
安装

npx @waffo/waffo-integrate

​
使用

安装后在 AI 助手中触发即可：
  • 输入 integrate waffo 或 接入waffo
  • Skill 会引导你完成：选择功能（支付/退款/订阅/Webhook）→ 检测语言 → 生成代码 → 运行验证测试

​
支持的语言和功能

语言SDK框架
Node.js@waffo/waffo-nodeExpress, NestJS, Fastify
Javacom.waffo:waffo-javaSpring Boot
Gogithub.com/waffo-com/waffo-goGin, Echo, Fiber, Chi
所有功能均可通过 Skill 自动集成：支付、退款、订阅（含升降级）、Webhook、商户配置查询、支付方式查询。

​
优势

指标使用 Skill手动集成
通过率100%（16/16 断言）75%（12/16）
集成时间约 128 秒约 192 秒
内置 13 条 API 规则自动防错（字段名、枚举值、必填项）需要自行查阅文档
详细文档参见 waffo-integrate GitHub。

​
手动集成

如果不使用 AI 工具，可以按以下步骤手动集成。

​
前置条件

  • Waffo 商户账号
  • API Key（从 Dashboard 获取）
  • RSA 密钥对（参见 认证与签名）
1

安装 SDK

npm install @waffo/waffo-node
2

初始化客户端

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,
});
3

创建一笔支付

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);
}
4

处理 Webhook 回调

参见 Webhook 章节。

​
下一步