waffo 0.1.0b0__tar.gz

waffo-0.1.0b0/.gitignore

@@ -0,0 +1,14 @@
+/.venv/
+/dist/
+/build/
+/*.egg-info/
+/uv.lock
+/.pytest_cache/
+/.ruff_cache/
+/.mypy_cache/
+/htmlcov/
+/.coverage
+/tests/e2e/application-test.yml
+/target/
+__pycache__/
+*.py[cod]

waffo-0.1.0b0/ADR.md

@@ -0,0 +1,138 @@
+# Python SDK Architecture Decision Record
+
+This document records the technical decisions for the Waffo Python SDK.
+
+## Summary Table
+
+| Decision Area | Choice | Rationale |
+|---|---|---|
+| Runtime Version | Python 3.9+ | Broad production support while keeping modern typing features available |
+| Dependency Strategy | Minimal runtime dependencies | Payment SDK should stay small, but Python benefits from well-maintained crypto, HTTP, and model libraries |
+| HTTP Client | httpx sync client | Modern API, timeout controls, TLS verification, and transport testability |
+| JSON Framework | Pydantic v2 + stdlib json | Generated models, alias support, validation, and stable JSON serialization |
+| Build Tool | pyproject.toml + hatchling | Current Python packaging standard with simple wheel/sdist output |
+| Test Framework | pytest | Standard Python test runner with fixtures, coverage, and vector-driven tests |
+| E2E Test Framework | pytest + playwright-python | Matches sandbox browser flows while keeping E2E independent from app frameworks |
+| Type System | Python type hints + Pydantic v2 models + PEP 561 | IDE support, runtime validation, and typed package consumers |
+| Code Style | ruff + mypy | Fast linting plus static checks |
+| Framework Adaptation | FastAPI first; Flask and Django examples | FastAPI is the primary modern Python web stack; Flask/Django remain common merchant stacks |
+| Package and Release Workflow | PyPI package `waffo`, import module `waffo`, `.github/workflows/publish-python.yml` | Release workflow validates version, tests, wheel/sdist, metadata, clean install, then publishes through PyPI trusted publishing |
+
+## Detailed Decisions
+
+### 1. Runtime Version
+
+**Decision:** Python 3.9+.
+
+**Rationale:** Python 3.9 is still common in production and supports the typing features needed by this SDK. CI will cover Python 3.9 through 3.13. Local development may use newer interpreters, but release support is 3.9-3.13 until the CI matrix is updated.
+
+**Alternatives Considered:** Python 3.8 would broaden support but is past normal support windows. Python 3.10+ would simplify typing syntax but exclude older merchant environments.
+
+### 2. Dependency Strategy
+
+**Decision:** Minimal runtime dependencies: `pydantic`, `httpx`, `cryptography`, `PyYAML`, and conditional `eval-type-backport` for Python 3.9.
+
+**Rationale:** RSA and TLS-sensitive code should use maintained libraries rather than hand-rolled implementations. Pydantic v2 lets generated models preserve OpenAPI field aliases and required/optional semantics.
+
+Python 3.9 needs `eval-type-backport` because generated Pydantic models use postponed annotations containing PEP 604 union syntax such as `str | None`; Pydantic evaluates those annotations at model construction time.
+
+**Alternatives Considered:** A zero-dependency SDK would reduce supply-chain surface but would push too much crypto, HTTP, and validation responsibility into this repo.
+
+### 3. HTTP Client / Network Layer
+
+**Decision:** Use a synchronous `httpx.Client` behind a `HttpTransport` protocol.
+
+**Rationale:** The first Python SDK is sync-only, matching the current plan and simplifying merchant integration. A transport protocol keeps tests deterministic and allows future async support without changing resource APIs.
+
+**Spec Notes:** `sdk-spec/HTTP_CLIENT.md` is authoritative for base URLs, headers, timeout defaults, response signature verification, and unknown-status errors. Python sends `X-API-VERSION=1.0.0`; the current Java SDK uses `v1`, which is tracked as cross-SDK drift.
+
+### 4. JSON Framework
+
+**Decision:** Use Pydantic v2 models with camelCase aliases and stdlib JSON for lower-level parsing when exact body bytes are needed.
+
+**Rationale:** API fields must come from `openapi.json`. Generated Pydantic models can preserve aliases, support extra service fields, and serialize with `exclude_none=True`.
+
+**Spec Notes:** Webhook response body bytes follow `sdk-spec/WEBHOOK_HANDLER.md` and `sdk-spec/test-vectors/webhook-response.json`.
+
+### 5. Build Tool
+
+**Decision:** Use `pyproject.toml` with hatchling.
+
+**Rationale:** This is the modern Python packaging path and works with PyPI trusted publishing.
+
+### 6. Test Framework
+
+**Decision:** Use pytest, pytest-cov, ruff, and mypy.
+
+**Rationale:** Pytest supports vector-driven tests cleanly. Coverage gates will start at 80% for core modules.
+
+### 7. E2E Test Framework
+
+**Decision:** Use pytest with playwright-python and optional pyngrok for webhook callbacks.
+
+**Rationale:** The SDK E2E surface requires real browser payment flows plus webhook delivery. Playwright gives stable browser automation while pytest keeps test orchestration simple.
+
+### 8. Type System
+
+**Decision:** Ship typed Python code (`py.typed`) and generated Pydantic v2 API models.
+
+**Rationale:** `openapi.json` is the only authority for API fields. Java/Node/Go are behavior references and known to have schema drift in `sdk-spec/SCHEMA_ALIGNMENT_CHECKLIST.md`.
+
+### 9. Code Style
+
+**Decision:** Use ruff for linting and formatting checks, and mypy for type checks.
+
+**Rationale:** Ruff is fast enough for local and CI use. Mypy catches API surface and generic response mistakes before release.
+
+### 10. Framework Adaptation
+
+**Decision:** Provide FastAPI examples first, plus Flask and Django webhook examples.
+
+**Rationale:** The SDK core stays framework-agnostic. Documentation and `waffo-integrate` templates will show raw-body webhook handling for common Python frameworks.
+
+### 11. Package and Release Workflow
+
+**Decision:** Publish the distribution name `waffo` to PyPI while preserving the import module `waffo`.
+
+**Workflow:** `.github/workflows/publish-python.yml`.
+
+**Tag Pattern:** `python-sdk-v*` (for example `python-sdk-v0.1.0b0`).
+
+**Version Source:** `pyproject.toml` `[project].version` and `src/waffo/_version.py` `__version__` must both equal the release version resolved from the tag or manual workflow input.
+
+**Build Artifact:** wheel + source distribution from `python -m build`.
+
+**Publish Auth:** PyPI trusted publishing/OIDC only. The workflow does not accept `PYPI_API_TOKEN`; PyPI must be configured with a trusted publisher before the release tag is pushed.
+
+**Artifact Verification:** The workflow runs ruff, mypy, unit tests/test vectors, `twine check`, and a clean temporary venv install/import smoke test before publishing.
+
+**Rationale:** Publishing is part of the SDK delivery contract. A release workflow that proves the built artifact can be installed catches packaging drift that source-tree tests miss.
+
+## Spec Gate
+
+The Python SDK implementation follows these current source-of-truth decisions:
+
+- API request/response fields are generated from `openapi.json`; public type packages may re-export or thinly wrap generated models but must not handwrite API fields.
+- RSA uses SHA256withRSA / RSASSA-PKCS1-v1_5, Base64 PKCS#8 private keys, and Base64 X.509 SubjectPublicKeyInfo public keys per `sdk-spec/RSA_SIGNING.md`.
+- Time formatting is UTC `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` per `sdk-spec/TIME_FORMAT.md`.
+- HTTP headers include `Content-Type`, `X-API-KEY`, `X-SIGNATURE`, `X-API-VERSION=1.0.0`, and `X-SDK-VERSION=waffo-python/{version}` per `sdk-spec/HTTP_CLIENT.md`.
+- Error classes are `WaffoError` and `WaffoUnknownStatusError` per `sdk-spec/ERROR_HANDLING.md`.
+- Webhook events are the five events in `sdk-spec/WEBHOOK_HANDLER.md`, including `SUBSCRIPTION_CHANGE_NOTIFICATION`. There is no standalone `SUBSCRIPTION_PAYMENT_NOTIFICATION`; `on_subscription_payment` is a fallback for `SUBSCRIPTION_STATUS_NOTIFICATION`.
+- Webhook success/failure response bodies are exactly `{"message":"success"}` and `{"message":"failed"}` per `sdk-spec/WEBHOOK_HANDLER.md` and `sdk-spec/test-vectors/webhook-response.json`.
+
+## Current Spec Drift Recorded Before Implementation
+
+| Area | Current Drift | Python Decision |
+|---|---|---|
+| Webhook response test rule | `sdk-spec/test-rules/04-webhook.md` still mentions `{"code":"SUCCESS"}` / `{"code":"FAILED"}` | Follow `WEBHOOK_HANDLER.md` + `webhook-response.json`; update stale rule when touching webhook spec |
+| Time vector | `sdk-spec/TIME_FORMAT.md` references missing `test-vectors/time-format.json` | Cover equivalent tests in `test_time_utils.py`; add vector if shared runners need it |
+| Config vector | `sdk-spec/TEST_SPECIFICATION.md` references missing `config-validation.json` | Treat actual 8 files in `sdk-spec/test-vectors/` as current vector set until spec doc is corrected |
+| API version header | Java has `ApiVersion.CURRENT = "v1"` while `HTTP_CLIENT.md` says `1.0.0` | Python uses `1.0.0` and records Java drift |
+| Schema fields | `SCHEMA_ALIGNMENT_CHECKLIST.md` lists Java/Node/Go field mismatches | Python generated models follow `openapi.json`, not existing SDK mismatches |
+
+## Decision Log
+
+| Date | Decision | Change | Author |
+|---|---|---|---|
+| 2026-05-08 | Initial Python SDK ADR | Created before implementation, with spec drift audit | Codex |
+| 2026-05-09 | Python release workflow | Added PyPI package/release workflow decision and artifact verification gates | Codex |

waffo-0.1.0b0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0b0
+
+- Initial Python SDK development scaffold.

waffo-0.1.0b0/CLAUDE.md

@@ -0,0 +1,154 @@
+# CLAUDE.md for waffo-python
+
+This file provides guidance for Claude Code when working with the Waffo Python SDK.
+
+## Project Overview
+
+Official Python SDK for Waffo Payment Services. This package is part of the Waffo SDK monorepo.
+
+## Project Rules
+
+1. This project is part of the Waffo SDK monorepo.
+2. API type fields are generated from `../../openapi.json`; do not handwrite API request/response fields.
+3. Core logic follows `../../sdk-spec/`.
+4. All shared test vectors in `../../sdk-spec/test-vectors/` must pass.
+5. README changes must start from the monorepo `../../README.md` and `../../README_CN.md`, then run `../../scripts/sync-readme.sh`.
+6. Technical decisions are documented in `ADR.md`; update ADR when changing runtime, dependencies, build/test tools, framework support, package name, or release workflow.
+
+## Architecture Decision Record
+
+See `ADR.md` for all technical decisions.
+
+| Decision | Choice |
+|---|---|
+| Runtime Version | Python 3.9+ |
+| Dependency Strategy | Minimal runtime dependencies |
+| HTTP Client | httpx sync client |
+| JSON Framework | Pydantic v2 + stdlib json |
+| Build Tool | pyproject.toml + hatchling |
+| Test Framework | pytest |
+| E2E Framework | pytest + playwright-python |
+| Framework Integrations | FastAPI, Flask, Django |
+| Package and Release Workflow | PyPI package `waffo`; workflow `.github/workflows/publish-python.yml`; tag pattern `python-sdk-v*` |
+
+## README Synchronization Rules
+
+The monorepo README files are the single source of truth for shared documentation:
+
+1. Update `../../README.md` and `../../README_CN.md` first.
+2. Update `../../scripts/sync-readme.js` when adding or renaming synced sections.
+3. Run `../../scripts/sync-readme.sh --verbose`.
+4. Add only Python-specific details in this package README.
+
+## Build & Test Commands
+
+```bash
+# From packages/waffo-python
+python -m pip install -e ".[dev]"
+ruff check src tests
+mypy src/waffo
+pytest tests/unit -v
+
+# From monorepo root
+./scripts/generate-types.sh python
+./scripts/sync-readme.sh --check
+```
+
+## Architecture
+
+```text
+src/waffo/
+├── __init__.py
+├── client.py
+├── core/
+│   ├── http_client.py
+│   └── webhook_handler.py
+├── resources/
+├── net/
+├── types/
+│   ├── api_response.py
+│   ├── config.py
+│   └── generated/
+├── utils/
+└── exceptions.py
+```
+
+## Key Implementation Notes
+
+### API Fields
+
+- `openapi.json` is authoritative.
+- Generated models live under `src/waffo/types/generated/`.
+- Public type packages may re-export generated models or add behavior-only thin wrappers.
+- Do not copy Java/Node/Go field mismatches into Python.
+
+### RSA Signing
+
+- Algorithm: SHA256withRSA / RSASSA-PKCS1-v1_5.
+- Private key: Base64 PKCS#8 DER.
+- Public key: Base64 X.509 SubjectPublicKeyInfo DER.
+- Validate keys during config initialization and fail fast with `S0007` / `S0002`.
+
+### HTTP Client
+
+- Use `httpx` behind a transport protocol.
+- Enforce TLS 1.2+.
+- Send `X-API-VERSION=1.0.0` and `X-SDK-VERSION=waffo-python/{version}`.
+- Query operations catch `WaffoUnknownStatusError` and return `ApiResponse.error("E0001", ...)`.
+
+### Webhook
+
+- Recognize the five event types in `../../sdk-spec/WEBHOOK_HANDLER.md`.
+- `SUBSCRIPTION_STATUS_NOTIFICATION` routes to `on_subscription_status` first, then falls back to `on_subscription_payment`.
+- There is no standalone `SUBSCRIPTION_PAYMENT_NOTIFICATION`.
+- Success response body is exactly `{"message":"success"}`; failure is exactly `{"message":"failed"}`.
+
+## E2E Test Error Logging
+
+Every assertion that checks an API response must include request identifiers and the full response body in the failure message. Do not use bare `assert response.is_success()`.
+
+## Release Checklist
+
+Before releasing:
+
+1. All unit tests and shared test vectors pass.
+2. Ruff and mypy pass.
+3. README sync passes.
+4. Full Python E2E matrix passes.
+5. Cross-repo `waffo-sdk-test`, `waffo-integrate`, and `waffo-integrate-test` validation passes.
+6. CHANGELOG is updated.
+7. `pyproject.toml` version and `src/waffo/_version.py` `__version__` match the release tag/input.
+
+## Release Workflow
+
+The Python SDK is published by `.github/workflows/publish-python.yml`.
+
+### Automatic release
+
+1. Complete the release checklist above.
+2. Make sure the release commit is on `main`.
+3. Create and push a tag matching `python-sdk-v{version}`, for example:
+
+```bash
+git tag python-sdk-v0.1.0b0
+git push origin python-sdk-v0.1.0b0
+```
+
+The workflow resolves `0.1.0b0`, verifies that the tag points to a commit on `origin/main`, checks package/runtime version consistency, runs ruff, mypy, unit tests/test vectors, builds wheel + sdist, runs `twine check`, performs a clean venv install/import smoke test, then publishes to PyPI.
+
+### Manual release
+
+Use GitHub Actions `Publish Python SDK to PyPI` -> `Run workflow` from `main`, with `version` set to the exact package version such as `0.1.0b0`.
+
+### PyPI trusted publishing
+
+Configure PyPI trusted publishing for this repository/workflow before pushing the release tag:
+
+| Field | Value |
+|---|---|
+| Repository owner | `waffo-com` |
+| Repository name | `waffo-sdk` |
+| Workflow filename | `publish-python.yml` |
+| Environment name | leave empty |
+
+The workflow publishes with GitHub OIDC only. Do not configure `PYPI_API_TOKEN` for this workflow.

waffo-0.1.0b0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Waffo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

waffo-0.1.0b0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include README_CN.md
+include LICENSE
+recursive-include src/waffo py.typed

waffo-0.1.0b0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: waffo
+Version: 0.1.0b0
+Summary: Official Waffo Payment Platform Python SDK
+Project-URL: Homepage, https://github.com/waffo-com/waffo-sdk/tree/main/packages/waffo-python
+Project-URL: Repository, https://github.com/waffo-com/waffo-sdk
+Project-URL: Issues, https://github.com/waffo-com/waffo-sdk/issues
+Author-email: Waffo <merchant.support@waffo.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: payment,payment-gateway,psp,sdk,subscription,waffo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: cryptography<47,>=42
+Requires-Dist: eval-type-backport<1,>=0.2; python_version < '3.10'
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml<7,>=6
+Provides-Extra: dev
+Requires-Dist: mypy<2.0,>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: e2e
+Requires-Dist: playwright>=1.40; extra == 'e2e'
+Requires-Dist: pyngrok>=7; extra == 'e2e'
+Requires-Dist: pytest-playwright>=0.5; extra == 'e2e'
+Description-Content-Type: text/markdown
+
+# Waffo Python SDK
+
+Official Python SDK for Waffo Payment Platform.
+
+This package is currently under active development. Shared documentation is maintained in the monorepo root `README.md` and will be synchronized here through `scripts/sync-readme.sh`.
+
+## Requirements
+
+- Python 3.9+
+- Runtime dependencies are declared in `pyproject.toml`.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest tests/unit -v
+```

waffo-0.1.0b0/README.md

@@ -0,0 +1,17 @@
+# Waffo Python SDK
+
+Official Python SDK for Waffo Payment Platform.
+
+This package is currently under active development. Shared documentation is maintained in the monorepo root `README.md` and will be synchronized here through `scripts/sync-readme.sh`.
+
+## Requirements
+
+- Python 3.9+
+- Runtime dependencies are declared in `pyproject.toml`.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest tests/unit -v
+```

waffo-0.1.0b0/README_CN.md

@@ -0,0 +1,17 @@
+# Waffo Python SDK
+
+Waffo Payment Platform 官方 Python SDK。
+
+该包正在开发中。共享文档以仓库根目录 `README_CN.md` 为准，并通过 `scripts/sync-readme.sh` 同步到本目录。
+
+## 环境要求
+
+- Python 3.9+
+- 运行时依赖见 `pyproject.toml`。
+
+## 开发
+
+```bash
+python -m pip install -e ".[dev]"
+pytest tests/unit -v
+```

waffo-0.1.0b0/docs/python-sdk-integration-acceptance-report-2026-05-09.md

@@ -0,0 +1,208 @@
+# Python SDK 集成验收报告
+
+## 概览
+
+| 字段 | 值 |
+|------|----|
+| 项目 | Waffo Python SDK FastAPI reference integration |
+| 日期 | 2026-05-09 |
+| SDK 版本 | `0.1.0b0` |
+| 环境 | Sandbox |
+| MID | `1200000256` |
+| 验收范围 | 支付、退款、订阅、订阅升降级、Webhook、商户配置、支付方式配置 |
+| 项目接口 | `packages/waffo-python/examples/fastapi_integration` |
+| Webhook Endpoint | `POST /api/waffo/webhook` |
+| 支付方式配置 | `payMethodConfig().inquiry()` 返回 268 条 active rows |
+| 自动化支付方式结果 | `CC_VISA`、`DANA`、`PIX`、`PERMATA`、`7ELEVEN` 已通过；`APPLEPAY`/`GOOGLEPAY` 需要设备钱包手工验收 |
+
+## 本轮补充修正
+
+| 问题 | 修正 |
+|------|------|
+| 订阅通知没有单独拆项 | 新增“订阅通知专项验收”，按 4 个通知类型分别列出结果和对应 ID |
+| `SUBSCRIPTION_CHANGE_NOTIFICATION` 未测 | 已补订阅升降级真实 Sandbox 验收，收到 `SUBSCRIPTION_CHANGE_NOTIFICATION` |
+| `/api/v1/subscription/change` 未测 | FastAPI 集成新增项目侧 `POST /api/subscriptions/{subscriptionRequest}/change`，底层调用 SDK `subscription().change()`，已通过 |
+| `/api/v1/subscription/change/inquiry` 未测 | FastAPI 集成新增项目侧 `GET /api/subscriptions/{originSubscriptionRequest}/changes/{subscriptionRequest}`，底层调用 SDK `subscription().change_inquiry()`，已通过 |
+| `Order ID / Key` 混用多种 ID | 所有主结果表拆为 `Request ID`、`Merchant ID`、`Acquiring ID`、`Subscription ID`、`Refund ID`、`Change Request ID` 等独立列 |
+| 报告中文可读性不足 | 本报告改为中文补充版，保留接口名、事件名、ID 字段英文原名 |
+
+## 集成配置
+
+| 参数 | 值 |
+|------|----|
+| 语言 / 框架 | Python / FastAPI |
+| SDK 初始化 | 单例 `Waffo` 注入 service layer |
+| `userTerminal` | `WEB` |
+| Checkout 模式 | 项目接口支持动态 `payMethodType`、`payMethodName`、`payMethodProperties` |
+| 订阅模式 | Payment-first subscription |
+| 订阅相关事件 | `PAYMENT_NOTIFICATION`、`SUBSCRIPTION_STATUS_NOTIFICATION`、`SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION`、`SUBSCRIPTION_CHANGE_NOTIFICATION` |
+| Webhook 业务逻辑 | 签名校验、幂等 key、store transaction、状态落库、履约/撤销/激活计数只执行一次 |
+| 凭据 | 从本地 Sandbox `application-test.yml` 查找路径读取，不提交 Git |
+
+## 项目接口覆盖
+
+| 模块 | 项目接口 | Waffo SDK/API 覆盖 |
+|------|----------|--------------------|
+| 支付 | `POST /api/payments` | `order().create()` / `/api/v1/order/create` |
+| 支付查询 | `GET /api/payments/{paymentRequestId}` | `order().inquiry()` / `/api/v1/order/inquiry` |
+| 取消订单 | `POST /api/payments/{paymentRequestId}/cancel` | `order().cancel()` / `/api/v1/order/cancel` |
+| 退款 | `POST /api/refunds` | `order().refund()` / `/api/v1/order/refund` |
+| 退款查询 | `GET /api/refunds/{refundRequestId}` | `refund().inquiry()` / `/api/v1/refund/inquiry` |
+| 订阅创建 | `POST /api/subscriptions` | `subscription().create()` / `/api/v1/subscription/create` |
+| 订阅查询 | `GET /api/subscriptions/{subscriptionRequest}` | `subscription().inquiry()` / `/api/v1/subscription/inquiry` |
+| 订阅管理 | `POST /api/subscriptions/{subscriptionRequest}/manage` | `subscription().manage()` / `/api/v1/subscription/manage` |
+| 订阅取消 | `POST /api/subscriptions/{subscriptionRequest}/cancel` | `subscription().cancel()` / `/api/v1/subscription/cancel` |
+| 订阅升降级 | `POST /api/subscriptions/{subscriptionRequest}/change` | `subscription().change()` / `/api/v1/subscription/change` |
+| 订阅升降级查询 | `GET /api/subscriptions/{originSubscriptionRequest}/changes/{subscriptionRequest}` | `subscription().change_inquiry()` / `/api/v1/subscription/change/inquiry` |
+| 商户配置 | `GET /api/merchant-config` | `merchantConfig().inquiry()` |
+| 支付方式配置 | `GET /api/payment-methods` | `payMethodConfig().inquiry()` |
+| Webhook | `POST /api/waffo/webhook` | `webhook().handle_webhook()` |
+
+## 主动验收结果
+
+| 验收项 | 结果 | Request ID | Merchant ID | Acquiring ID | Subscription ID | Refund ID | Change Request ID | 说明 |
+|--------|------|------------|-------------|--------------|-----------------|-----------|-------------------|------|
+| merchant-config | PASS | - | `1200000256` | - | - | - | - | 通过项目接口查询商户配置 |
+| payment-method-config | PASS | - | `1200000256` | - | - | - | - | 查询到 268 条 active rows |
+| order-create | PASS | `pay_...` | `ord_...` | `A202605090723532146976` | - | - | - | 项目接口返回 checkout URL 并落库 |
+| payment-success (`CC_VISA`) | PASS | `pay_...` | `ord_...` | `A202605090723532146976` | - | - | - | Playwright 完成 checkout，查询状态 `PAY_SUCCESS` |
+| payment-failure (`CC_VISA`) | PASS | `pay_...` | `ord_...` | `A202605090724013246977` | - | - | - | 失败卡关闭订单，`fulfillmentCount=0` |
+| cancel-unpaid-order | PASS | `pay_...` | `ord_...` | `A202605090724098676978` | - | - | - | 项目取消接口返回 `ORDER_CLOSE` |
+| order-create-error | PASS | `pay_4b8a3343192c4aec822d934e587a` | - | - | - | - | - | 非法金额返回用户友好 `400`，本地订单标记 `FAILED` |
+| pay-method-coverage | PASS WITH MANUAL ITEMS | 多个 | 多个 | 见“支付方式覆盖” | - | - | - | 覆盖 card、e-wallet、special params、VA/bank、OTC；设备钱包手工 |
+| refund-success | PASS | `pay_...` | - | `A202605090725023336982` | - | `ref_3ecf891874634297a0984f697e6e` | - | DANA 支付源触发退款 webhook |
+| refund-inquiry | PASS | `pay_...` | - | `A202605090725023336982` | - | `ref_3ecf891874634297a0984f697e6e` | - | 项目查询返回 `ORDER_PARTIALLY_REFUNDED` |
+| refund-webhook | PASS | `pay_...` | - | `A202605090725023336982` | - | `ref_3ecf891874634297a0984f697e6e` | - | `REFUND_NOTIFICATION` 后 `revokeCount=1` |
+| webhook-idempotency | PASS | `pay_...` | - | `A202605090725023336982` | - | - | - | 重放 DANA payment webhook，`fulfillmentCount` 保持 `1` |
+| subscription-create | PASS | `sub_80d68d452cd0486c841520b07080` | `msub_...` | - | `SC202605091445554676139` | - | - | 项目接口返回订阅 checkout URL 并落库 |
+| subscription-activation | PASS | `sub_80d68d452cd0486c841520b07080` | `msub_...` | - | `SC202605091445554676139` | - | - | 完成订阅 checkout，`SUBSCRIPTION_STATUS_NOTIFICATION` 激活本地状态 |
+| subscription-inquiry | PASS | `sub_80d68d452cd0486c841520b07080` | `msub_...` | - | `SC202605091445554676139` | - | - | 项目查询接口返回 `ACTIVE` |
+| subscription-manage | PASS | `sub_80d68d452cd0486c841520b07080` | `msub_...` | - | `SC202605091445554676139` | - | - | 项目 manage 接口返回 management URL |
+| subscription-renewal | PASS | `sub_80d68d452cd0486c841520b07080` | `msub_...` | - | `SC202605091445554676139` | - | - | 管理页 mock 触发续期通知，`renewalCount=1` |
+| subscription-change | PASS | `sub_80d68d452cd0486c841520b07080` | `msubchg_...` | - | `SC202605091446207776140` | - | `subchg_1d4ee1ea844f4461851400260` | 调用 `/api/v1/subscription/change`，完成升降级 checkout，状态 `SUCCESS` |
+| subscription-change-inquiry | PASS | `sub_80d68d452cd0486c841520b07080` | `msubchg_...` | - | `SC202605091446207776140` | - | `subchg_1d4ee1ea844f4461851400260` | 调用 `/api/v1/subscription/change/inquiry`，返回 `SUCCESS` |
+| subscription-cancel | PASS | `subchg_1d4ee1ea844f4461851400260` | `msubchg_...` | - | `SC202605091446207776140` | - | - | 取消升降级后的新订阅，返回 `MERCHANT_CANCELLED` |
+
+## 订阅通知专项验收
+
+| 通知类型 | 结果 | Request ID | Acquiring ID | Subscription ID | Change Request ID | 状态 / 说明 |
+|----------|------|------------|--------------|-----------------|-------------------|-------------|
+| `PAYMENT_NOTIFICATION` | PASS | - | `A202605091445555496872` | - | - | 订阅首期支付通知，`orderStatus=PAY_SUCCESS`，项目 handler 按 `productName=SUBSCRIPTION` 过滤业务履约但保留 webhook delivery |
+| `SUBSCRIPTION_STATUS_NOTIFICATION` | PASS | `sub_80d68d452cd0486c841520b07080` | - | `SC202605091445554676139` | - | 订阅激活通知，`subscriptionStatus=ACTIVE` |
+| `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` | PASS | `sub_80d68d452cd0486c841520b07080` | - | `SC202605091445554676139` | - | 管理页续期 mock 后收到周期变更通知，`renewalCount=1` |
+| `SUBSCRIPTION_CHANGE_NOTIFICATION` | PASS | `sub_80d68d452cd0486c841520b07080` | - | `SC202605091446207776140` | `subchg_1d4ee1ea844f4461851400260` | 订阅升降级完成通知，`subscriptionChangeStatus=SUCCESS` |
+
+## 支付方式覆盖
+
+| 支付方式 | 国家 / 币种 | 类型 | 状态 | Request ID | Acquiring ID | 说明 |
+|----------|-------------|------|------|------------|--------------|------|
+| `CC_VISA` | HKG / HKD | Card | TESTED | `pay_...` | `A202605090723532146976` | 信用卡代表路径，覆盖成功支付 |
+| `DANA` | IDN / IDR | E-wallet | TESTED | `pay_...` | `A202605090724164096979` | 印尼 e-wallet 代表路径，Sandbox 成功模拟 |
+| `PIX` | BRA / BRL | Special Params | TESTED | `pay_...` | `A202605090724283856980` | 填写 name/email，使用 `payMethodProperties={"cpf":"52998224725"}` 后成功 |
+| `PERMATA` | IDN / IDR | VA / Bank | TESTED | `pay_...` | `A202605090724444766981` | 印尼 virtual-account/bank 代表路径 |
+| `7ELEVEN` | PHL / PHP | OTC | TESTED | `pay_...` | `A202605090810521186219` | 使用有效金额 `300.00` 后通过 |
+| `APPLEPAY` | Multiple | Device Pay | MANUAL | `ap_4e784d8024cc4414a47411291bc4f` | `A202605090802098626168` | 已创建手工验证订单，需要 Apple Pay 设备/浏览器完成 |
+| `GOOGLEPAY` | Multiple | Device Pay | MANUAL | - | - | 需要 Android/Chrome 或设备钱包环境 |
+
+Sandbox active method sample: `DC_VISA`, `CC_MASTERCARD`, `DC_MASTERCARD`, `CC_VISA`, `APPLEPAY`, `GOOGLEPAY`, `CC_AMEX`, `SHOPEEPAY`, `ALIPAYHK`, `MERCADOPAGO`, `DANA`, `PIX`, `ALIPAY`, `7ELEVEN`, `PERMATA`.
+
+## 7ELEVEN 金额边界
+
+`payMethodConfig().inquiry()` 能确认 `7ELEVEN` 在 `TWN` 与 `PHL` active，但公开 SDK config response 不暴露 amount min/max。本轮通过 Sandbox order-create 探测确认：
+
+| 国家 | 币种 | 已验证最小值 | 已验证最大值 | 证据 |
+|------|------|--------------|--------------|------|
+| `TWN` | `TWD` | `17.00` | `20000.00` | `16.00` 返回 `A0008`；`17.00` 成功。`20000.00` 成功；`20001.00` 返回 `A0008` |
+| `PHL` | `PHP` | `300.00` | `50000.00` | `299.00` 返回 `A0008`；`300.00` 成功。`50000.00` 成功；`50001.00` 返回 `A0008` |
+
+## Apple Pay 手工验证订单
+
+`APPLEPAY` 在 Sandbox 对 `ONE_TIME_PAYMENT` 的 `HKG`、`USA`、`GBR`、`JPN`、`BRA`、`EU_LIST` active；对 `SUBSCRIPTION` 的 `HKG` 和 `BRA` active。已创建一笔一次性支付订单供开发者在真实 Apple Pay 环境验证：
+
+| 字段 | 值 |
+|------|----|
+| `paymentRequestId` | `ap_4e784d8024cc4414a47411291bc4f` |
+| `merchantOrderId` | `ord_b4d06829ea484778a3f6ab407970` |
+| `acquiringOrderId` | `A202605090802098626168` |
+| 国家 / 币种 / 金额 | `HKG` / `HKD` / `15.00` |
+| Checkout URL | `https://checkout-sandbox.waffo.com/VueXeyNSoEe9DJceA5acx9wcEf5qDUF1TVhHqN9BKPZjZjUJFTNuQPRspbitS4pz5KnjpLoYdE7H3znXb5aDUBVwLn3X2sA65kxSRcWzk77tBM5VGMRLPT2tp1H?lang=zh-Hant-HK&mock` |
+
+## 参数与数据完整性检查
+
+- [x] `paymentRequestId`、`refundRequestId`、`subscriptionRequest`、升降级新 `subscriptionRequest` 均为不超过 32 位的商户侧请求 ID。
+- [x] 所有写接口调用前先落库请求 ID，再调用 Waffo。
+- [x] `orderDescription` / subscription description 具体可读。
+- [x] `goodsName` 与 `goodsUrl` 已提供。
+- [x] `userEmail` 使用 `{userId}@example.com` 或明确邮箱，避免使用 `test` 字样。
+- [x] `userTerminal=WEB` 与当前 FastAPI reference integration 一致。
+- [x] success / failed / cancel redirect URL 均有设置。
+- [x] SDK 自动注入 UTC ISO-8601 timestamp。
+- [x] 非卡支付可通过项目接口透传 country、currency、method type/name、`payMethodProperties`。
+- [x] 退款 webhook 以 `acquiringOrderId` 匹配本地退款上下文。
+- [x] Webhook 幂等处理可防止重复履约、重复撤销、重复订阅激活或重复升降级处理。
+
+## 被动验证
+
+| Case | 说明 | 结果 | 证据 |
+|------|------|------|------|
+| Payment 1.3 | `C0005` 渠道拒绝 | COVERED | Service 映射为用户友好的 retry/switch-method 错误 |
+| Payment 1.4 | `A0011` 幂等冲突 | COVERED | Request ID 独立生成，UUID hex 截断 32 位 |
+| Payment 1.5 | `C0001` 系统不可用 | COVERED | Service 映射为 retry/switch-method 错误 |
+| Payment 1.6 | `E0001` unknown status | COVERED | `WaffoUnknownStatusError` 后用同一 request ID 查询恢复 |
+| Payment 3.3 | Webhook 签名失败 | COVERED | SDK 在业务 handler 前拒绝无效签名 |
+| Payment 4.5 | Cancel unknown status | COVERED | Cancel recovery 查询订单，不盲目关闭本地状态 |
+| Payment 5.4 | Refund 幂等冲突 | COVERED | `refundRequestId` 独立生成并先落库 |
+| Payment 5.6 | Refund unknown status | COVERED | Refund recovery 用同一 request ID 查询 |
+| Subscription 1.6 | Subscription 幂等冲突 | COVERED | `subscriptionRequest` 独立生成并先落库 |
+| Subscription 1.8 | Subscription unknown status | COVERED | Subscription recovery 用同一 request ID 查询 |
+| Subscription Change | Change unknown status | COVERED | Change recovery 用 `originSubscriptionRequest + subscriptionRequest` 查询 |
+| Subscription 3.5 | Subscription webhook 签名失败 | COVERED | SDK 在业务 handler 前拒绝无效签名 |
+| Data D1 | 时间字段格式 | COVERED | SDK timestamp auto-injection 使用共享 time utility |
+| Data D2 | 写接口先落库 | COVERED | Store insert 在 order/refund/subscription/change API 前执行 |
+
+## 执行命令与结果
+
+```bash
+uv run --python 3.13 --extra dev --extra e2e --with fastapi --with uvicorn ruff check src tests examples
+uv run --python 3.13 --extra dev --extra e2e --with fastapi --with uvicorn pytest tests/unit -q
+uv run --python 3.13 --extra dev --extra e2e --with fastapi --with uvicorn mypy src/waffo examples
+WAFFO_E2E=1 uv run --python 3.13 --extra dev --extra e2e --with fastapi --with uvicorn pytest tests/e2e -v -s --tb=short
+WAFFO_E2E=1 uv run --python 3.13 --extra dev --extra e2e --with fastapi --with uvicorn pytest tests/integration -v -s --tb=short
+WAFFO_E2E=1 uv run --python 3.13 --extra dev --extra e2e --with fastapi --with uvicorn pytest tests/integration/test_fastapi_integration_acceptance.py::test_phase_c2_project_subscription_endpoints -v -s --tb=short
+./scripts/generate-types.sh validate
+```
+
+结果摘要：
+
+```text
+ruff: all checks passed
+unit: 50 passed in 2.61s
+mypy: success, no issues in 41 source files
+e2e: 8 passed in 68.91s
+integration: 4 passed in 111.88s
+pay-method rerun: 1 passed in 65.23s
+subscription change rerun: 1 passed in 46.85s
+sync validate: all SDKs appear to be in sync
+```
+
+## 本轮代码补充
+
+| 区域 | 修正 |
+|------|------|
+| FastAPI 项目接口 | 新增 `POST /api/subscriptions/{subscriptionRequest}/change` 与 `GET /api/subscriptions/{originSubscriptionRequest}/changes/{subscriptionRequest}` |
+| Service 层 | 新增 `change_subscription()` 与 `query_subscription_change()`，底层分别调用 SDK `subscription().change()` 和 `subscription().change_inquiry()` |
+| Store 层 | 新增 `SubscriptionChangeRecord`，按 `originSubscriptionRequest + subscriptionRequest` 记录升降级请求、状态、订阅 ID、幂等 key |
+| Webhook handler | `SUBSCRIPTION_CHANGE_NOTIFICATION` 改为独立 handler，不再复用 subscription status handler |
+| Integration test | 订阅验收补充四类 webhook 等待与记录：首期支付、订阅状态、周期变更、升降级完成 |
+| 报告 | 中文化，拆分 ID 列，订阅四通知单独列证据 |
+
+## 结论
+
+**CONDITIONAL PASS**
+
+Python SDK 已通过 FastAPI 项目式集成验收，覆盖支付、退款、订阅、订阅续期、订阅升降级、升降级查询和 4 类订阅相关通知。原先 `CC_VISA` 单一覆盖、`SUBSCRIPTION_CHANGE_NOTIFICATION` 未实际测试、订阅升降级 API 未测、ID 列混用的问题已补齐。
+
+仍保留条件通过的原因：
+
+1. `APPLEPAY` 需要真实 Apple Pay 设备/浏览器手工验证。
+2. `GOOGLEPAY` 需要真实 Google Pay 设备/浏览器手工验证。

waffo-0.1.0b0/examples/__init__.py

@@ -0,0 +1 @@
+"""Runnable Waffo Python SDK integration examples."""