本页记录 Waffo API 文档和外部合同的修订序列。表中的
v1.3 不是请求头 X-API-VERSION 的值;原始 HTTP 当前使用 1.0.0,SDK 会自动管理该请求头,请勿手动设置或覆盖。查找 SDK 包(Node.js / Java / Go / Python / PHP)的版本更新,请见 SDK 更新日志。| 版本 | 日期 | 变更 |
|---|---|---|
| v1.3 | 2026-11-16 | 退款查询响应 AcqOrderRefundInquiry 新增必填 merchantId。Payout 创建请求 PayoutOrderRequest 将 notifyUrl、payeeType、payoutAmount、purpose 标记为必填;这是 OpenAPI 必填约束收紧,依赖该规格生成客户端或校验请求的调用方需复核,不能仅据此推断运行时校验已改变。接口路径、字段类型、枚举和长度约束不变。 |
| v1.3 | 2026-11-13 | 收银台新增 fr-FR、de-DE、nl-NL、it-IT、cs-CZ、sv-SE 语言标签,支持通过 paymentInfo.cashierLanguage 指定;浏览器 Accept-Language 新增 fr、de、nl、it、cs、sv 主语言匹配。国家或地区回退映射不变。 |
| v1.3 | 2026-11-09 | 公开错误码表新增 A0076–A0078,用于 Subscription seat add-on 已支付、支付中和取消中的状态校验;新增 A0080,表示该支付方式没有支持 MIT 的支付渠道。四个错误码的 HTTP status 均为 400。 |
| v1.3 | 2026-11-09 | 新增 POST /api/v1/payout/beneficiary-fields/inquiry,用于查询指定国家、币种、Payout 方式及收款人类型的创单必填和条件必填字段。请求必填 country、payeeType、payoutCurrency、payoutMethodType;payoutMethodName 对 EWALLET 和 PROXY 条件必填。响应包含字段约束、允许值、格式及参考文档。最新 Payout facade 将已弃用的 PayeeInfo.payeeType 和派生属性 payeeFullName 从公开 schema 隐藏;依赖这些 schema 属性生成代码的调用方需复核,不能据此推断运行时字段已删除。 |
| v1.3 | 2026-11-02 | Wallet 查询响应将顶层 network、asset、payTo 替换为 paymentOptions[],每个选项包含上述字段及 decimals;这是需要调用方适配的兼容风险。订单创建、session 更新及创建/查询响应新增 mppInfo;Subscription 查询的 PaymentDetail 新增 repaymentDetails。支付方式配置新增 userCurrency,并明确 currency 为订单币种、金额上下限使用该币种。订单和 Subscription 风险数据的 userRegistrationIp、userLastSeenIp 长度上限从 24 放宽到 64。Payout payoutMethodName 在 BANK_ACCOUNT 且省略时,默认规则改为 {country}_BANK。补充 14 个 Issuing API 的操作说明,包括异步资金处理、卡冻结及敏感卡信息获取限制;endpoint、required、type 和 enum 均无变化。 |
| v1.3 | 2026-10-30 | 公开错误码表新增 A0071–A0075,用于智能体支付凭据和 Subscription 分期还款状态校验;新增 A0079,用于没有卡支付方式的支付 session 不能创建卡 tokenization session 的场景。 |
| v1.3 | 2026-10-27 | 新增 5 个 Withdraw API,覆盖账户余额和流水查询,以及 Withdraw 咨询、创建、查询;新增 3 个 Risk Control transaction limit API,覆盖创建、查询、更新。主 OpenAPI 不再包含 3 个 /web/v1/session/* 浏览器 session 端点。 |
| 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,并移除旧字段 mid 和 subMid;feeAmount 不再推荐使用,请读取 actFeeAmount |
| 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 | 初始发布 |