> ## 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.

# SDK 概览与选择

> 解答商户选择 Waffo SDK 时最常见的问题：五种服务端 SDK 的包名与版本要求、SDK 代为处理的签名与请求头、两类错误与幂等键、何时直接调 HTTP 接口，以及升级注意事项。

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

## Waffo 提供哪些官方 SDK？

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

| 语言 | 包名 | 版本要求 | 官网页面 |
| - | - | - | - |
| Node.js | `@waffo/waffo-node` | Node.js >= 18.0.0 | [https://waffo.com/docs/zh/developer-docs/sdk/nodejs.md](https://waffo.com/docs/zh/developer-docs/sdk/nodejs.md) |
| Java | `com.waffo:waffo-java` | Java 8 及以上（支持 8、11、17、21），Maven 3.6+ 或 Gradle 6.0+ | [https://waffo.com/docs/zh/developer-docs/sdk/java.md](https://waffo.com/docs/zh/developer-docs/sdk/java.md) |
| Go | `github.com/waffo-com/waffo-go/v2` | Go 1.20+，无外部依赖 | [https://waffo.com/docs/zh/developer-docs/sdk/go.md](https://waffo.com/docs/zh/developer-docs/sdk/go.md) |
| Python | `waffo` | Python 3.9+，需要 pip | [https://waffo.com/docs/zh/developer-docs/sdk/python.md](https://waffo.com/docs/zh/developer-docs/sdk/python.md) |
| PHP | `waffo/waffo-php` | PHP 8.0+，需要 Composer，以及 cURL、JSON、OpenSSL 扩展 | [https://waffo.com/docs/zh/developer-docs/sdk/php.md](https://waffo.com/docs/zh/developer-docs/sdk/php.md) |

## 哪个 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 帮我做了什么？

| 事项 | SDK 的行为 |
| - | - |
| 请求签名 | 请求头里的 `X-SIGNATURE` 由 SDK 用你配置的商户私钥生成 |
| `X-API-VERSION` 请求头 | SDK 自己管理，不要手动设置或覆盖。详见[API 版本与变更记录](https://waffo.com/docs/zh/support/api-versioning-and-changelog-faq.md) |
| `merchantId`、时间戳 | SDK 自动注入，不需要在每次请求里手填 |
| Webhook 验签与响应 | `handleWebhook()` 一次完成验签、事件解析、分发和响应体（含响应签名）生成。你只需要把**未改动的原始请求 body** 和 `X-SIGNATURE` 请求头交给 SDK，再把 SDK 生成的响应体原样返回 |
| 沙箱 / 生产切换 | 设置 `Environment.SANDBOX` 或 `Environment.PRODUCTION`，不需要手改 URL |

Webhook 的验签原理和不用 SDK 时的手动验签步骤见[鉴权与签名 FAQ](https://waffo.com/docs/zh/support/auth-signature-faq.md)和官网 [Webhook signature verification](https://waffo.com/docs/zh/developer-docs/webhook/signature-verification.md) 页面。

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

SDK 把失败分成两类，处理方式完全不同（Node.js、Go、Python、PHP 为 `WaffoUnknownStatusError` / `WaffoError`，Java 对应的是 `WaffoUnknownStatusException` / `WaffoException`）：

| 错误类型 | 含义 | 你该做什么 |
| - | - | - |
| 状态未知（`WaffoUnknownStatus…`） | 请求**可能已经成功**（例如网络超时） | 官网的做法是：**先调用查询接口确认结果，不要重新创建**。支付用 `paymentRequestId` 查询，订阅用 `subscriptionRequest` |
| 客户端错误（`WaffoError` / `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`，见[调试与集成加速工具](https://waffo.com/docs/zh/support/developer-tools-and-integration-accelerators-faq.md)。
* **你已经在用 Stripe 的订阅，只想低成本迁移**：见[调试与集成加速工具](https://waffo.com/docs/zh/support/developer-tools-and-integration-accelerators-faq.md)里的 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 版本与变更记录](https://waffo.com/docs/zh/support/api-versioning-and-changelog-faq.md)。

## 相关入口

* 官网 SDK 总览与各语言页面：[https://waffo.com/docs/zh/developer-docs/sdk/nodejs.md](https://waffo.com/docs/zh/developer-docs/sdk/nodejs.md)（其余语言把路径末尾换成 `java`、`go`、`python`、`php`）
* SDK 发布记录：[https://waffo.com/docs/zh/developer-docs/sdk/changelog.md](https://waffo.com/docs/zh/developer-docs/sdk/changelog.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.