> ## 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 Node.js、Java、Go 和 Python SDK 版本发布更新日志。

<Note>
  本页记录 **Waffo SDK 包**（Node.js / Java / Go / Python）的版本发布。查找 **Waffo API** 的版本历史，请见 [API 版本历史](/docs/zh/developer-docs/tools-and-references/references/changelog)。
</Note>

## Node.js SDK (@waffo/waffo-node)

<Steps>
  <Step title="v2.6.0 (2026-07-17) — 最新">
    * 新增 Wallet 地址查询、x402 订单数据、promotion 字段和类型化 x402 支付 Webhook 数据
    * 保留已废弃的旧订单和订阅字段/类型，同时让当前 wire contract 与最新 OpenAPI specification 对齐
    * 发布校验会在 shared schema field vector 过期时失败
  </Step>

  <Step title="v2.5.1 (2026-07-06)">
    * 兼容性修复：`subscription().create()` 省略 `subscriptionManagementUrl` 时保持向后兼容
    * `subscriptionManagementUrl` 字段仍受支持，但 SDK 不会在发送 API 调用前拒绝既有请求
  </Step>

  <Step title="v2.5.0 (2026-05-13)">
    * 新增 `subscription().update()`，支持更新订阅金额、试用期金额和计划金额
    * `ProductInfo` 新增 `scheduledAmounts`，支持订阅创建、变更、更新和查询中的计划金额
    * 新增订阅扩展信息、Token 卡信息、卡 BIN 和商品详情等类型化字段
    * `Order().Capture()` 未传 `captureRequestedAt` 时自动注入当前时间
  </Step>

  <Step title="v2.4.0 (2026-03-14)">
    * 类型对齐：所有 SDK 类型字段与 openapi.json 定义保持一致
    * 修复 `merchantConfig` 和 `payMethodConfig` 的接口路径
    * 为 `CaptureOrderParams` 添加 `captureRequestedAt` 字段
    * 为 `PaymentInfo` 添加 `captureMode` 字段
    * 添加 Capture 端到端（E2E）测试与 Schema 字段校验测试
  </Step>

  <Step title="v2.3.4 (2026-03-10)">
    * 将 `RefundOrderParams.requestedAt` 设为可选；SDK 将自动注入当前 UTC 时间
  </Step>

  <Step title="v2.3.3 (2026-03-03)">
    * 修复 `RefundOrderParams` 字段名与类型，使其与 openapi.json 对齐
    * 将 `notifyUrl` 重命名为 `refundNotifyUrl`
    * 添加退款 Webhook 端到端（E2E）测试
  </Step>

  <Step title="v2.3.2 (2026-03-02)">
    * 增加对 `SUBSCRIPTION_CHANGE_NOTIFICATION` Webhook 事件的处理
  </Step>

  <Step title="v2.3.1 (2026-03-01)">
    * **重要修复**：`buildSuccessResponse()` 返回 `{"message":"success"}`，不再返回 `{"status":"success"}`
  </Step>

  <Step title="v2.3.0 (2026-02-24)">
    * 自动注入时间戳：未提供时，`orderRequestedAt` 与 `requestedAt` 将自动设置
  </Step>
</Steps>

***

## Java SDK (waffo-java)

<Steps>
  <Step title="v1.5.0 (2026-07-17) — 最新">
    * 新增 Wallet 地址查询、x402 订单数据、promotion 字段和类型化 x402 支付 Webhook 数据
    * 保留已废弃的旧订单和订阅字段/类型，同时让当前 wire contract 与最新 OpenAPI specification 对齐
    * 发布校验会在 shared schema field vector 过期时失败
  </Step>

  <Step title="v1.4.1 (2026-07-06)">
    * 兼容性发布：保持 `subscriptionManagementUrl` 可选
    * 对齐 `payMethodDetails` 的 SDK schema 和 E2E 校验门禁
  </Step>

  <Step title="v1.4.0 (2026-06-02)">
    * 支持将 `orderFailedReason`、`refundFailedReason` 和订阅 `failedReason` 按对象或 JSON 字符串解析
    * 保留既有失败原因访问方式，并在收到普通字符串时保留原始说明
  </Step>

  <Step title="v1.3.0 (2026-05-13)">
    * 新增 `subscription().update()`，支持更新订阅金额、试用期金额和计划金额
    * 新增 `SubscriptionScheduledAmount`、`SubscriptionUpdateProductInfo`、`UpdateSubscriptionParams` 和 `UpdateSubscriptionData`
    * 新增订阅扩展信息、Token 卡信息、卡 BIN 和商品详情等类型化字段
  </Step>

  <Step title="v1.2.0 (2026-03-14)">
    * 类型对齐：所有 SDK 类型字段与 openapi.json 定义保持一致
    * 修复 Java 8 兼容性问题
    * 添加 Capture 端到端（E2E）测试与 Schema 字段校验测试
  </Step>

  <Step title="v1.1.2 (2026-03-10)">
    * 自动注入 `RefundOrderParams.requestedAt`
    * 添加 `SUBSCRIPTION_CHANGE_NOTIFICATION` Webhook 处理
    * 修复 `RefundOrderParams` 字段对齐问题
  </Step>

  <Step title="v1.1.1 (2026-03-01)">
    * **重要修复**：`buildSuccessResponse()` 返回 `{"message":"success"}`，不再返回 `{"status":"SUCCESS"}`
  </Step>

  <Step title="v1.1.0 (2026-02-24)">
    * 自动注入时间戳
    * 将 `CancelOrderParams.orderRequestedAt` 类型从 String 改为 Instant
  </Step>
</Steps>

***

## Go SDK (waffo-go)

<Steps>
  <Step title="v1.5.0 (2026-07-17) — 最新">
    * 新增 Wallet 地址查询、x402 订单数据、promotion 字段和类型化 x402 支付 Webhook 数据
    * 保留已废弃的旧订单和订阅字段/类型，同时让当前 wire contract 与最新 OpenAPI specification 对齐
    * 发布校验会在 shared schema field vector 过期时失败
  </Step>

  <Step title="v1.4.1 (2026-07-06)">
    * 兼容性发布：保持 `SubscriptionManagementURL` 可选
    * 对齐 `payMethodDetails` 的 SDK schema 和 E2E 校验门禁
  </Step>

  <Step title="v1.4.0 (2026-05-13)">
    * 新增 `Subscription().Update()`，支持更新订阅金额、试用期金额和计划金额
    * 新增 `ScheduledAmount`，支持订阅创建、变更、更新和查询中的计划金额
    * 新增订阅扩展信息、Token 卡信息、卡 BIN 和商品详情等类型化字段
    * `Order().Capture()` 未传 `CaptureRequestedAt` 时自动注入当前时间
    * 扩展 Schema 字段校验覆盖必填字段和嵌套订阅/订单结构
  </Step>

  <Step title="v1.3.2 (2026-05-12)">
    * Webhook 失败原因解析支持 JSON 字符串格式的 `orderFailedReason`、`refundFailedReason` 和订阅 `failedReason`
    * 新增支付、退款和订阅失败回调测试
    * 退款 E2E 流程改用 DANA，并让沙箱前置条件缺失时显式失败或跳过
  </Step>

  <Step title="v1.3.1 (2026-03-16)">
    * 修复 Go module 代理缓存问题
  </Step>

  <Step title="v1.3.0 (2026-03-14)">
    * 类型对齐：所有 SDK 类型字段与 openapi.json 定义保持一致
    * 修复 `merchantConfig` 和 `payMethodConfig` 的接口路径
    * 添加 `RefundStatus`、`OrderStatus` 与 `SubscriptionStatus` 常量
    * 添加 Capture 端到端（E2E）测试与 Schema 字段校验测试
  </Step>

  <Step title="v1.2.2 (2026-03-03)">
    * 修复 `RefundOrderParams` 字段，使其与 openapi.json 对齐
    * 添加退款 Webhook 端到端（E2E）测试
  </Step>

  <Step title="v1.2.1 (2026-03-01)">
    * **重要修复**：`BuildSuccessResponse()` 返回 `{"message":"success"}`，不再返回 `{"status":"success"}`
  </Step>

  <Step title="v1.2.0 (2026-02-24)">
    * 自动注入时间戳
  </Step>
</Steps>

***

## Python SDK (waffo)

<Steps>
  <Step title="v0.3.0b0 (2026-07-17) — 最新">
    * 新增 Wallet 地址查询、x402 订单数据、promotion 字段和 x402 Webhook payload 覆盖
    * `merchantInfo` 省略时，Wallet 查询参数支持由 SDK 从配置自动注入
    * 保留已废弃的生成模型名和旧订单/订阅字段，维持源码兼容
    * schema drift 校验现在会发现过期的 shared schema field vector
  </Step>

  <Step title="v0.2.0b1 (2026-07-06)">
    * 兼容性发布：保持 `subscriptionManagementUrl` 可选
    * 对齐 `payMethodDetails` 的 SDK schema 和 E2E 校验门禁
  </Step>

  <Step title="v0.2.0b0 (2026-05-13)">
    * 新增 `subscription.update()`，支持更新订阅金额、试用期金额和计划金额
    * 新增计划金额模型，覆盖订阅创建、变更、更新和查询字段
    * 扩展订单 capture 时间戳自动注入和 schema 字段校验覆盖
  </Step>

  <Step title="v0.1.0b0 (2026-05-09)">
    * 发布首个 Python beta 版本
    * 支持支付、退款、订阅、商户配置、支付方式配置和 Webhook 签名验证
  </Step>
</Steps>