集成指南

选择集成路线

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

API integration

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

选择产品方案

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

接入必需 API

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

查看 API Reference 细节

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

完成额外支付配置

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

提交验收结果

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

AI integration tool

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

安装 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

npx @waffo/waffo-integrate --claude

npx @waffo/waffo-integrate --cursor

使用

安装后在 AI 助手中触发即可：

输入 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 自动集成：支付、退款、订阅（含升降级）、Webhook、商户配置查询、支付方式查询。

优势

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

详细文档参见 waffo-integrate GitHub。

手动集成

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

前置条件

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

安装 SDK

npm install @waffo/waffo-node

<dependency>
    <groupId>com.waffo</groupId>
    <artifactId>waffo-java</artifactId>
    <version>1.5.0</version>
</dependency>

go get github.com/waffo-com/waffo-go

初始化客户端

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 com.waffo.Waffo;
import com.waffo.types.config.WaffoConfig;
import com.waffo.types.config.Environment;

WaffoConfig config = WaffoConfig.builder()
    .apiKey(System.getenv("WAFFO_API_KEY"))
    .privateKey(System.getenv("WAFFO_PRIVATE_KEY"))
    .waffoPublicKey(System.getenv("WAFFO_PUBLIC_KEY"))
    .merchantId(System.getenv("WAFFO_MERCHANT_ID"))
    .environment(Environment.SANDBOX)
    .build();

Waffo waffo = new Waffo(config);

import (
    waffo "github.com/waffo-com/waffo-go"
    "github.com/waffo-com/waffo-go/config"
)

cfg, _ := config.NewConfigBuilder().
    APIKey(os.Getenv("WAFFO_API_KEY")).
    PrivateKey(os.Getenv("WAFFO_PRIVATE_KEY")).
    WaffoPublicKey(os.Getenv("WAFFO_PUBLIC_KEY")).
    MerchantID(os.Getenv("WAFFO_MERCHANT_ID")).
    Environment(config.Sandbox).
    Build()

client := waffo.New(cfg)

创建一笔支付

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

处理 Webhook 回调

参见 Webhook 章节。

快速开始

核心概念

集成

Webhook

SDK

工具与参考

选择集成路线

API integration

AI integration tool

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

安装

使用

支持的语言和功能

优势

手动集成

前置条件

下一步

​选择集成路线

​API integration

​AI integration tool

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

​安装

​使用

​支持的语言和功能

​优势

​手动集成

​前置条件

​下一步

选择集成路线

API integration

AI integration tool

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

安装

使用

支持的语言和功能

优势

手动集成

前置条件

下一步