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

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

有。官网提供沙箱环境的 Postman Collection（JSON 文件），内置常用接口的预设请求。 导入步骤： 在 Postman 里选择 Import → Upload Files，上传下载的 JSON 文件，然后配置环境变量。如果浏览器只是预览文件，请右键链接选择「链接另存为」，并保留 .postman_collection.json 文件名。 环境变量： 集合包含的接口： 创建支付、查询支付、取消订单、申请退款、查询退款、创建订阅、查询订阅、取消订阅、更新订阅、查询更新、订阅管理，以及商户配置查询和支付方式配置查询。 签名要注意：
  • 集合的请求头里带有 X-SIGNATURE: {{signature}}。每次发请求前，你要用商户私钥对原始 JSON body 做 SHA256WithRSA 签名，把 Base64 结果填进 signature 变量。
  • 只要改了请求 body，就要重新签名。
  • 不要把生产环境的私钥存进 Postman 集合文件。
Postman 集合是沙箱调试工具。用它能快速验证请求格式，不能替代上线前的验收。

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

沙箱不连接真实支付通道，而是提供模拟器，让你直接控制支付结果。下单后打开 orderAction 里的收银台地址，页面上会出现模拟按钮： 点击后，Waffo 会自动向你的 notifyUrl 发送 PAYMENT_NOTIFICATION 通知。沙箱收银台只是模拟界面，没有真实的支付方式选择和卡号输入，所有支付方式的模拟流程相同。需要模拟真实输卡流程（例如测试 3DS）时，使用官网列出的测试卡号。更多模拟范围见沙箱模拟范围 FAQ和沙箱测试 FAQ。

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

沙箱的通知要发到公网可访问的地址。本地调试时，用内网穿透工具把本地端口暴露成公网 URL，官网给出的例子：
把得到的公网地址配置为 notifyUrl。Webhook 的投递、重试和响应规则见回调通知投递契约 FAQ，验签见鉴权与签名 FAQ。

​
能不能让 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 技术支持群确认。
它能做什么，不能做什么： 这里的「AI」指的是用 AI 工具来完成 SDK 接入。如果你想了解让 AI Agent 用稳定币付款，那是另一个主题，见稳定币支付。 验收的具体要求和用例模板见官网集成验收标准，上线前还要对照上线收款之前需要完成哪些事？。

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

可以考虑 Stripe 迁移工具。它的定位很窄，请先确认是否适合你。 它做什么： 在你 Stripe 订阅的已付周期结束之前，让客户提前在 Waffo 收银台完成卡信息录入和所需的 3DS 验证。Waffo 此时不提前扣款，到交接时间自动发起首次扣款；你可以通过查询看到「等待中」状态，也可以在交接前取消，阻止那次扣款。 接入分三步： 把 Stripe 客户端换成 WaffoStripe.client(...)；在目标订阅上加路由标记（metadata.source=waffo）和交接时间；接入 Waffo 的 Webhook。你现有的 com.stripe.* 类型和调用方式保持不变。 它是怎么路由的： 所以不带标记的一次性支付、订阅、客户对象、价格对象都和以前完全一样，你可以只迁移一部分订阅，两边并行。 使用前要知道： 交接时间的设置（用 Stripe 周期结束时间作为 billing_cycle_anchor，并设置 proration_behavior=none）、不支持的用法和原因码，见官网Stripe 迁移工具和Stripe 迁移工具接入指南（有中文版）。

​
Octopus 沙箱怎么测试？

Octopus 的沙箱测试需要用官方的 Octopus 测试 App，而不是生产 App。官网页面提供了：
  • 测试 App 的下载方式（推荐用 Android 测试；iOS 通过 TestFlight 安装）；
  • 测试账号、验证码和支付密码；
  • 完整的操作截图。
大致流程：
  1. 下载并安装测试 App。 测试 App 不能使用真实的生产 Octopus 卡。
  2. 准备测试卡。 先注册一张测试卡；并关闭最近三个月的交易记录，否则会报错。
  3. 要测扫码支付（O!ePay 钱包）时： 用香港手机号注册钱包账号（需要能收短信），再用前面注册的测试卡给它转入余额。
  4. 登录测试账号后扫码支付。
  5. 遇到限额提示时： 在账户设置里直接调整限额。
测试账号、固定验证码和支付密码请以官网页面为准，本页不重复列出。

​
相关入口