> ## 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 官方的开发辅助工具：Postman 集合、沙箱模拟器、本地接收 Webhook、AI 集成工具 waffo-integrate、Stripe 迁移工具以及 Octopus 沙箱测试，各自的用途与限制。

本页介绍 Waffo 官方提供的几类开发辅助工具：Postman 集合、沙箱模拟器、本地收 Webhook 的做法、AI 辅助集成工具 `waffo-integrate`、Stripe 订阅迁移工具，以及 Octopus 沙箱测试。每项都回答「它是什么、什么时候该用、有什么限制」，具体步骤以官网对应页面为准。

## 有没有 Postman 集合可以直接调接口？

有。官网提供沙箱环境的 Postman Collection（JSON 文件），内置常用接口的预设请求。

**导入步骤：** 在 Postman 里选择 **Import → Upload Files**，上传下载的 JSON 文件，然后配置环境变量。如果浏览器只是预览文件，请右键链接选择「链接另存为」，并保留 `.postman_collection.json` 文件名。

**环境变量：**

| 变量 | 含义 | 示例 |
| - | - | - |
| `base_url` | API 地址 | `https://api-sandbox.waffo.com` |
| `api_key` | API Key | 在 Portal 获取 |
| `merchant_id` | 商户 ID | `M000001` |
| `signature` | 请求 body 的 SHA256WithRSA 签名（Base64） | 每次发请求前生成 |

**集合包含的接口：** 创建支付、查询支付、取消订单、申请退款、查询退款、创建订阅、查询订阅、取消订阅、更新订阅、查询更新、订阅管理，以及商户配置查询和支付方式配置查询。

**签名要注意：**

* 集合的请求头里带有 `X-SIGNATURE: {{signature}}`。每次发请求前，你要用商户私钥对**原始 JSON body** 做 SHA256WithRSA 签名，把 Base64 结果填进 `signature` 变量。
* **只要改了请求 body，就要重新签名。**
* 不要把生产环境的私钥存进 Postman 集合文件。

Postman 集合是沙箱调试工具。用它能快速验证请求格式，不能替代上线前的验收。

## 沙箱里怎么模拟支付成功或失败？

沙箱不连接真实支付通道，而是提供模拟器，让你直接控制支付结果。下单后打开 `orderAction` 里的收银台地址，页面上会出现模拟按钮：

| 按钮 | 效果 |
| - | - |
| 支付成功 | 订单状态变为 `PAY_SUCCESS` |
| 支付失败 | 订单状态变为 `ORDER_CLOSE` |

点击后，Waffo 会自动向你的 `notifyUrl` 发送 `PAYMENT_NOTIFICATION` 通知。沙箱收银台只是模拟界面，没有真实的支付方式选择和卡号输入，所有支付方式的模拟流程相同。需要模拟真实输卡流程（例如测试 3DS）时，使用官网列出的测试卡号。更多模拟范围见[沙箱模拟范围 FAQ](https://waffo.com/docs/zh/support/sandbox-simulation-limits-faq.md)和[沙箱测试 FAQ](https://waffo.com/docs/zh/support/sandbox-testing-faq.md)。

## 本地开发时怎么收到 Webhook？

沙箱的通知要发到公网可访问的地址。本地调试时，用内网穿透工具把本地端口暴露成公网 URL，官网给出的例子：

```bash theme={null}
# cloudflared
cloudflared tunnel --url http://localhost:3000

# ngrok
ngrok http 3000
```

把得到的公网地址配置为 `notifyUrl`。Webhook 的投递、重试和响应规则见[回调通知投递契约 FAQ](https://waffo.com/docs/zh/support/webhook-delivery-contract-faq.md)，验签见[鉴权与签名 FAQ](https://waffo.com/docs/zh/support/auth-signature-faq.md)。

## 能不能让 AI 编码工具帮我接入？

可以，用官方的 AI 集成工具 **`waffo-integrate`**。它是一个 Skill，通过交互式向导帮你完成 SDK 接入，支持 Codex、Claude Code、Cursor 等 AI 编码工具。官网当前版本为 `1.7.0`，支持 Node.js、Java、Go、Python 和 PHP 项目。

**使用流程：**

1. 在你的项目里打开 Codex、Claude Code 或 Cursor；
2. 运行 `npx @waffo/waffo-integrate` 安装 Skill（会自动检测工具；也可以加 `--codex`、`--agents`、`--claude`、`--cursor` 指定）；
3. 对 AI 助手说「集成 Waffo 支付」或 `integrate waffo`；
4. 回答业务问题，选择需要的能力：支付、退款、订阅、Webhook、商户配置查询、支付方式查询；
5. 预览并确认代码，工具会生成 SDK 初始化、各服务、Webhook 处理和测试代码；
6. 运行验证，覆盖支付、退款、订阅和 Webhook 流程；
7. 把生成的测试报告发给 Waffo 技术支持群确认。

**它能做什么，不能做什么：**

| 事项 | 说明 |
| - | - |
| 语言识别 | 根据项目文件自动判断语言（例如 `package.json` 对应 Node.js，`pom.xml` 对应 Java，`go.mod` 对应 Go，`composer.json` 对应 PHP） |
| 生成内容 | SDK 初始化、支付 / 退款 / 订阅服务、Webhook 处理、测试文件和 `.env.example` |
| 内置规则 | 官网说明内置 33 条代码生成规则，用来避免常见错误，例如请求 ID 不超过 32 个字符、订阅和支付用的字段名不同、Webhook 必须验签、写操作遇到状态未知时的恢复处理等 |
| 验证 | 代码生成并构建通过后，工具按阶段运行验收测试并记录证据。证据不全或测试失败时，会输出「验证被阻止」或失败摘要，不会把未完成的验证标记为通过 |
| 不是什么 | 它是帮你**写和验证**接入代码的工具，不是 Waffo 的验收本身。是否通过上线验收，以 Waffo 技术支持确认为准 |

这里的「AI」指的是用 AI 工具来完成 SDK 接入。如果你想了解让 AI Agent 用稳定币付款，那是另一个主题，见[稳定币支付](https://waffo.com/docs/zh/support/stablecoin-payments-faq.md)。

验收的具体要求和用例模板见官网[集成验收标准](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/acceptance-criteria.md)，上线前还要对照[上线收款之前需要完成哪些事？](https://waffo.com/docs/zh/support/production-go-live-faq.md)。

## 我现在用 Stripe 订阅，能低成本迁到 Waffo 吗？

可以考虑 **Stripe 迁移工具**。它的定位很窄，请先确认是否适合你。

**它做什么：** 在你 Stripe 订阅的已付周期结束之前，让客户提前在 Waffo 收银台完成卡信息录入和所需的 3DS 验证。Waffo 此时不提前扣款，到交接时间自动发起首次扣款；你可以通过查询看到「等待中」状态，也可以在交接前取消，阻止那次扣款。

**接入分三步：** 把 Stripe 客户端换成 `WaffoStripe.client(...)`；在目标订阅上加路由标记（`metadata.source=waffo`）和交接时间；接入 Waffo 的 Webhook。你现有的 `com.stripe.*` 类型和调用方式保持不变。

**它是怎么路由的：**

| 情况 | 去向 |
| - | - |
| 订阅模式的 Checkout 创建请求，带 `metadata.source=waffo` | Waffo |
| 对象 id 以 `wsub_` 或 `wcs_` 开头的查询 | Waffo |
| 其他所有调用 | 原样走 Stripe，不受影响 |

所以不带标记的一次性支付、订阅、客户对象、价格对象都和以前完全一样，你可以只迁移一部分订阅，两边并行。

**使用前要知道：**

| 事项 | 说明 |
| - | - |
| 可用语言 | 目前只有 **Java**（`com.waffo:waffo-java-stripe`）。Node.js、Python、Go 版本官网标注为「即将推出」 |
| 支持范围 | 第一阶段针对**托管收银台的订阅**：订阅模式、单个商品行、银行卡或支持循环扣款的钱包。是官网接口的一个子集，不是完整 API |
| 不是原生 SDK | 它是对你已有的官方 `stripe-java` 的一层手写兼容封装，覆盖的是一部分订阅 Checkout 场景。**新接入请直接使用原生 SDK**，见[SDK 概览与选择](https://waffo.com/docs/zh/support/sdk-overview-and-selection-faq.md) |
| 不会改 Stripe 那边 | 工具只管 Waffo 一侧的申请、查询和取消，**不会修改原来的 Stripe 订阅**。你需要用现有的 Stripe 代码或后台，在同一个交接时间结束旧订阅 |
| 上线前 | 请先持久化幂等键，并保存 Waffo 订阅 id 与你的业务订单之间的对应关系 |

交接时间的设置（用 Stripe 周期结束时间作为 `billing_cycle_anchor`，并设置 `proration_behavior=none`）、不支持的用法和原因码，见官网[Stripe 迁移工具](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/stripe-adapter)和[Stripe 迁移工具接入指南](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/stripe-adapter-integration)（有中文版）。

## Octopus 沙箱怎么测试？

Octopus 的沙箱测试需要用官方的 Octopus 测试 App，而不是生产 App。官网页面提供了：

* 测试 App 的下载方式（推荐用 Android 测试；iOS 通过 TestFlight 安装）；
* 测试账号、验证码和支付密码；
* 完整的操作截图。

大致流程：

1. **下载并安装测试 App。** 测试 App 不能使用真实的生产 Octopus 卡。
2. **准备测试卡。** 先注册一张测试卡；并**关闭最近三个月的交易记录**，否则会报错。
3. **要测扫码支付（O!ePay 钱包）时：** 用香港手机号注册钱包账号（需要能收短信），再用前面注册的测试卡给它转入余额。
4. **登录测试账号后扫码支付。**
5. **遇到限额提示时：** 在账户设置里直接调整限额。

测试账号、固定验证码和支付密码请以官网页面为准，本页不重复列出。

## 相关入口

* 官网 Postman 集合：[https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/postman.md](https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/postman.md)
* 官网沙箱模拟器：[https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/sandbox-simulator.md](https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/sandbox-simulator.md)
* 官网 AI 集成工具：[https://waffo.com/docs/zh/developer-docs/integration/ai-integration.md](https://waffo.com/docs/zh/developer-docs/integration/ai-integration.md)
* 官网 Stripe 迁移工具：[https://waffo.com/docs/zh/developer-docs/tools-and-references/references/stripe-adapter.md](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/stripe-adapter.md)
* 官网 Octopus 沙箱测试：[https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/octopus-sandbox-e2e.md](https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/octopus-sandbox-e2e.md)
* 官网集成验收标准：[https://waffo.com/docs/zh/developer-docs/tools-and-references/references/acceptance-criteria.md](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/acceptance-criteria.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.