本页记录 Waffo API 文档和外部合同的修订序列。表中的
v1.3 不是请求头 X-API-VERSION 的值；原始 HTTP 当前使用 1.0.0，SDK 会自动管理该请求头，请勿手动设置或覆盖。查找 SDK 包（Node.js / Java / Go / Python / PHP）的版本更新，请见 SDK 更新日志。| 版本 | 日期 | 变更 |
|---|---|---|
| v1.3 | 2026-10-26 | 公开错误码表新增 A0063–A0070，用于支付 session 有效性、重复订单、确认令牌、提交状态、必填字段、支付凭据、预支付校验和报价过期校验场景。 |
| v1.3 | 2026-10-23 | 新增 14 个 Issuing API，覆盖 accounts、funding、cards 和 transactions；新增 7 个 Waffo Element session API，覆盖订单和 Subscription 的 session 创建/更新，以及浏览器 session 的 info、validate、confirm。Chargeback 文件下载由 GET /api/v1/chargeback/file/download 的查询参数和 302 跳转改为 POST JSON 请求，响应返回 downloadUrl 和 expiresAt，下载 URL 有效期为 5 分钟；文件上传新增必填 X-SIGNATURE，使用 multipart 的 meta JSON 字符串和 file，meta 包含必填的 merchantId、filename、sha256、timestamp，签名使用原始 meta 字符串，上传响应仍不返回 X-SIGNATURE。Subscription 创建新增 paymentTokenData、paymentInfo.userPaymentAccessToken、userInfo.userAgent 和 userInfo.userBrowserIp，直接传入 Apple Pay/Google Pay paymentTokenData 时后两个浏览器字段条件必填；补充 scheduledCancelAt 不得晚于 Subscription 结束时间、无结束时间时不得超过当前时间后 2 年，以及使用前需联系 Waffo 技术支持开通的说明。Payout payoutMethodProperty.bankCode 的说明由必填改为条件字段。 |
| v1.3 | 2026-10-22 | 补充 PAYMENT_NOTIFICATION 的 subscriptionInfo.subscriptionEvent 取值说明：PERIOD_CHARGE（周期扣款）、USER_ADD_PAYMENT_METHOD（新增支付方式）、TOPUP_CHARGE（Subscription 升级或增购补差价）；明确主单状态通知与周期最终支付结果通知的区别，并补充周期权益发放前的周期、金额和支付结果校验建议。 |
| v1.3 | 2026-10-19 | 明确 Payout 创建请求、创建响应和查询响应的收款人信息说明：payeeType 为 INDIVIDUAL 时使用 payeeInfo，为 BUSINESS 时使用 receivingBusinessInfo；字段结构和必填标记不变。 |
| v1.3 | 2026-10-16 | 补充错误码 A0061：商户无权发起 MIT（HTTP 400）。 |
| v1.3 | 2026-10-12 | 新增撤销 Subscription 计划取消的 API POST /api/v1/subscription/resume；Subscription 取消请求、取消响应和查询响应新增 scheduledCancelAt，计划取消尚未生效时取消响应的 orderStatus 为 ACTIVE；订单创建、退款及对应查询新增 taxInfo，订单和退款查询新增 orderTaxAmount，orderAmount 和 refundAmount 不再无条件标记为必填，支持含税金额替代输入，refundAmount 长度上限为 24；Payout 创建和查询新增 payeeType、receivingBusinessInfo，PayeeInfo.payeeType 标记为弃用且不再标记为必填，创建请求的 payeeInfo 不再标记为必填；Payout EWALLET 的 PHONE 标识类型说明从默认值调整为推荐值 |
| v1.3 | 2026-10-09 | 公开错误代码表新增 A0051、A0052、A0053，用于申报税额校验场景；新增 A0056、A0058、A0059、A0060、A0062，用于订阅计划取消校验场景 |
| v1.3 | 2026-09-29 | Subscription 创建、查询和管理响应的 subscriptionStatus 状态说明新增 PLATFORM_CANCELLED |
| v1.3 | 2026-09-08 | 订阅修改请求和响应新增 seat add-on top-up topupInfo，订阅查询的支付明细新增 topupDetails；订阅创建、变更和查询相关支付信息新增 payMethodCountry，订阅变更请求新增 cashierLanguage；Payout 订单数据 PayoutOrderData 新增 purpose 并移除 feeStatus、mid、subMid，PayeeInfo.payeeId 不再标记为必填；Chargeback 证据字段 EvidenceField.evidenceFields 从公开 schema 中移除；Chargeback 和 Reported Fraud 列表响应分页 schema 命名调整为 ApiPageResponse... |
| v1.3 | 2026-09-07 | 公开错误代码表新增 A0055、B0014、B0015、B0016，用于订阅修改处理中和卡状态校验场景 |
| v1.3 | 2026-08-24 | 新增 Reported Fraud 查询 API POST /api/v1/fraud-report/list；订单和订阅支付信息新增 receiptTemplateId；Chargeback 详情和列表响应新增 merchantOrderId；Chargeback 查询请求的 chargebackId 和 originalOrderId 不再标记为必填 |
| v1.3 | 2026-08-21 | 公开错误代码表新增 A0048、A0049、A0050、A0054，用于订阅套餐变更进行中、取消中、已成功支付和并发处理场景 |
| v1.3 | 2026-08-20 | 新增点卡充值（Waffo Point Topup）API：GET /redirect 签名跳转端点、POST /api/v1/gamepin/fulfillment-inquiry 履行结果查询，以及 FULFILLMENT_RESULT_NOTIFY 履行结果通知 Webhook |
| v1.3 | 2026-07-24 | 将订阅创建请求 subscriptionManagementUrl 标记为必填；支付方式详情 PayMethodDetail 新增币种、订单金额上下限、支付方式类型和是否支持退款字段，currentStatus 不再标记为必填；Payout 订单数据 PayoutOrderData 恢复 mid 和 subMid，并更新 Payout 收款账号、描述和用途说明；卡信息 AcqCardInfo 的卡号、有效期、CVV 和持卡人姓名不再标记为必填 |
| v1.3 | 2026-07-22 | 补充订单创建和订阅创建请求中 userEmail 的说明，明确该字段必填；缺少真实邮箱时应传入按用户 ID 构造的唯一 fallback 邮箱，并避免使用占位值或多人共用同一邮箱 |
| v1.3 | 2026-07-20 | 调整 OpenAPI 嵌套对象 schema 命名，使用父请求或响应上下文区分 MerchantInfo、PromotionInfo、SubscriptionInfo 等共享对象，避免组件名冲突 |
| v1.3 | 2026-07-17 | 公开错误代码表新增 A0047，用于表示收银台页面语言值不符合 IETF BCP 47 |
| v1.3 | 2026-07-15 | Payout 订单数据 PayoutOrderData 新增实际手续费字段 actFeeAmount，并移除旧字段 feeAmount、mid 和 subMid |
| v1.3 | 2026-07-13 | 新增订单 capture API POST /api/v1/order/capture，用于 Auth-Capture 手动扣款确认 |
| v1.3 | 2026-07-08 | 临时同步公开错误代码表，补充 A0025、A0028、A0033-A0037、A0039-A0046、B0008-B0013、D0002；订阅创建和订阅变更的 payMethodName 最大长度从 24 调整为 256；补充订阅创建 paymentInfo 示例；优化订单创建 payMethodProperties 说明 |
| v1.2 | 2023-09-15 | 新增 Direct Payment 产品类型；更新错误码 A0019、A0020、A0021 |
| v1.1 | 2023-05-31 | 新增 riskData 风控数据；为 BNPL 支付方式新增 AddressInfo 和 GoodsInfo；更新错误码 |
| v1.0 | 2023-03-15 | 初始发布 |