Skip to main content
本页回答商户在选 Waffo SDK 时最常问的问题：有哪些语言、版本要求是什么、SDK 帮我做了什么、什么时候不用 SDK。安装步骤和完整示例以官网各语言 SDK 页面为准，本页只给结论和入口。

​
Waffo 提供哪些官方 SDK？

目前有五个服务端 SDK，覆盖支付、退款、订阅、Webhook、商户配置与支付方式配置查询：

​
哪个 SDK 已经稳定，哪个还是测试版？

以官网当前页面为准：
  • Python SDK 目前处于 beta（官网安装示例为 waffo==0.5.0b0，或用 --pre 安装最新预发布版）。上线前请到 PyPI 确认最新版本。
  • PHP SDK 当前最新版本为 v0.3.0，上线前请到 Packagist 确认。
  • Node.js、Java、Go 的最新版本以 SDK changelog 为准。
具体版本号会随发布变化，请不要把本页的数字写进你的依赖锁定策略，以包管理平台和官网 SDK changelog 为准。

​
SDK 帮我做了什么？

Webhook 的验签原理和不用 SDK 时的手动验签步骤见鉴权与签名 FAQ和官网 Webhook signature verification 页面。

​
调用失败时，SDK 会区分哪两种错误？

SDK 把失败分成两类，处理方式完全不同（Node.js、Go、Python、PHP 为 WaffoUnknownStatusError / WaffoError，Java 对应的是 WaffoUnknownStatusException / WaffoException）： 另外，接口返回的业务错误（返回码不是成功）不会抛异常，用响应对象的 isSuccess() 判断（官网 Node.js、Java、PHP 示例的写法）。

​
幂等键要注意什么？

支付用 paymentRequestId、订阅用 subscriptionRequest 作为幂等键，官网要求：
  • 最长 32 个字符，每个新请求生成唯一值；
  • 发请求之前先持久化到你的数据库；
  • 重试时复用原来的幂等键，不要生成新的。

​
我该怎么选 SDK，还是直接调 HTTP 接口？

  • 你的后端是上面五种语言之一：优先用 SDK。签名、请求头、Webhook 验签这些最容易出错的环节都由 SDK 完成。
  • 你的后端是其他语言：直接调用 REST 接口。请求都是 HTTP POST、Content-Type: application/json（UTF-8）、TLS 1.2 及以上；用 SHA256WithRSA 对整个 body 签名后放入 X-SIGNATURE，并发送 X-API-KEY 和 X-API-VERSION: 1.0.0。官网 API 示例页有 curl 样例。
  • 想让 AI 编码工具帮你生成接入代码：用官方的 waffo-integrate，见调试与集成加速工具。
  • 你已经在用 Stripe 的订阅，只想低成本迁移：见调试与集成加速工具里的 Stripe 迁移工具。它不是原生 SDK，不要混用。

​
新版本发布后要不要升级？有什么要注意？

SDK 的发布说明都在官网 SDK changelog（五种语言各一节）。升级前请看这几点：
  • 大版本升级可能有不兼容变更。 例如官网记录过：Node.js SDK v3.0.0 里 CreateOrderParams.paymentTokenData、商户配置查询返回的限额字段改成了 string，与 API 里的 JSON 字符串字段一致，需要你在应用里自行解析。
  • 新接口字段通常在新版本里才有类型。 例如订阅加座补差用的 topupInfo，在 2026-09-04 发布的各语言 SDK 新版本中增加了类型支持。
  • Java 升级时，官网提示：如果只替换 JAR，请清理旧的缓存或 shaded 副本并做一次干净构建。
SDK 的版本号和 API 的文档修订版本是两套独立的版本，不要混淆，见API 版本与变更记录。

​
相关入口