bebebus-merchant-openapi-sdk 1.0.0__py3-none-any.whl

bebebus_merchant_openapi_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: bebebus-merchant-openapi-sdk
+Version: 1.0.0
+Summary: 商户支付 OpenAPI Python SDK（零第三方依赖）
+Author: bebebus
+License: MIT
+Project-URL: Homepage, https://github.com/bebebus/SDK/tree/main/python
+Project-URL: Repository, https://github.com/bebebus/SDK
+Project-URL: Issues, https://github.com/bebebus/SDK/issues
+Keywords: payment,openapi,merchant,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Dynamic: license-file
+
+# 商户支付 OpenAPI — Python SDK
+
+**零第三方依赖**的 Python 3 SDK：HTTP 用 `urllib.request`，签名用 `hmac`/`hashlib`，测试用标准库 `unittest`。无需 `pip install` 任何运行时依赖。
+
+签名算法与服务端签名实现逐字节一致，单测对 [`../test-vectors.json`](../test-vectors.json) 全量复现 `base` 与 `sign`。
+
+## 引入（无需安装依赖）
+
+把 `openapi_sdk/` 目录放进你的项目（或把本目录加入 `sys.path` / `PYTHONPATH`）即可：
+
+```python
+import sys
+sys.path.insert(0, "/path/to/python")
+
+from openapi_sdk import Client, Config, Environment
+```
+
+可选地用标准打包安装（仍零依赖）：
+
+```bash
+cd python
+pip install .        # 或 python3 -m build；本身不拉任何第三方运行时依赖
+```
+
+## 快速开始
+
+```python
+from openapi_sdk import Client, Config, Environment, ApiError, TransportError
+
+config = Config(
+    merchant_no="M00000001",
+    api_key="ak_xxx",
+    api_secret_pay="sk_pay_xxx",        # pay 类接口 + 代收/退款回调
+    api_secret_payout="sk_payout_xxx",  # payout 类接口 + 代付回调
+    environment=Environment.SANDBOX,    # 或 Environment.PRODUCTION（须显式传 base_url）
+)
+client = Client(config)
+
+try:
+    # 金额是最小单位整数：10000 = 1 元
+    order = client.pay_create(
+        out_order_no="ORD1", amount=10000, currency="PHP",
+        pay_method="gcash", country="PH",
+        notify_url="https://m.example.com/api/notify/pay",
+    )
+    print(order["pay_url"])
+except ApiError as e:        # 业务失败 code != 0
+    print(e.code, e.message, e.data)
+except TransportError as e:  # HTTP / 网络 / 超时
+    print(e, e.status_code)
+```
+
+## 双环境与自定义基址
+
+| 环境 | 基址 |
+|------|------|
+| `Environment.PRODUCTION` | 无内置基址，**必须显式传 `base_url`** |
+| `Environment.SANDBOX` | `http://127.0.0.1:3090/api/open/v1` |
+
+正式真实地址按上级代理专有域名派生（`https://api.<agent_domain>/api/open/v1`），用 `base_url=` 显式传入。选 `PRODUCTION` 又不传 `base_url` 会抛 `ValueError`（提示 `baseUrl is required`）：
+
+```python
+config = Config(
+    merchant_no="M00000001", api_key="ak_xxx",
+    api_secret_pay="...", api_secret_payout="...",
+    base_url="https://api.agent.example.com/api/open/v1",  # 正式环境必传
+)
+```
+
+## 全部 11 个端点
+
+代收（密钥 `api_secret_pay`，自动选用）：
+
+| 方法 | 端点 |
+|------|------|
+| `pay_create(...)` | `/merchant/pay/create` |
+| `pay_query(order_no=, out_order_no=)` | `/merchant/pay/query` |
+| `pay_methods_query(country=)` | `/merchant/pay-methods/query` |
+| `balance_query(currency=)` | `/merchant/balance/query` |
+| `pay_test_complete(result=, ...)` | `/merchant/pay/test/complete`（仅测试密钥） |
+
+代付（密钥 `api_secret_payout`，自动选用）：
+
+| 方法 | 端点 |
+|------|------|
+| `payout_create(...)` | `/merchant/payout/create` |
+| `payout_query(payout_no=, out_payout_no=)` | `/merchant/payout/query` |
+| `payout_banks_query(pay_method=, country=, currency=)` | `/merchant/payout/banks/query` |
+| `payout_proof_query(payout_no=, out_payout_no=)` | `/merchant/payout/proof/query` |
+| `payout_receipt_query(..., inline=)` | `/merchant/payout/receipt/query` |
+| `payout_test_complete(result=, ...)` | `/merchant/payout/test/complete`（仅测试密钥） |
+
+约定：
+
+- 每请求自动注入 `merchant_no`/`api_key`/`timestamp`(Unix 秒)/唯一 `nonce` 与 `sign`。
+- 值为 `None` 的参数不放入请求体、也不参与签名。
+- `payout_receipt_query` 的 `inline` 以整数 **1/0** 发送（`True`→1 内联 base64 图片；`False`→0 返回带 token 的 URL）。
+- 金额是最小单位整数（`10000 = 1 元`），用 `int` 类型传入。
+- 成功返回 `data`（dict）；`code != 0` 抛 `ApiError`（携带 `code`/`message`/`data`）；HTTP/网络错误抛 `TransportError`。
+- 需要原始信封时用 `client.call_raw(path, body, secret)`（不因 `code != 0` 抛异常）。
+
+## 签名工具（可单独使用）
+
+```python
+from openapi_sdk import build_sign_base, sign, verify_callback
+
+base = build_sign_base(payload, secret)   # 逐字节可断言的签名 base
+sig  = sign(payload, secret)              # HMAC-SHA256 -> hex 小写
+ok   = verify_callback(callback, secret)  # 时序安全（hmac.compare_digest），字段无关
+```
+
+## 回调验签 + 处理
+
+见 [`examples/callback_verify.py`](examples/callback_verify.py)：解析原始 body → `verify_callback`（时序安全）→ 按 `status` 幂等处理（success/failed）→ 应答 **HTTP 200 + 纯文本 `success`**。代收回调用 `api_secret_pay`、代付回调用 `api_secret_payout`，示例各演示一次。验签失败不回成功，让平台重试；处理务必幂等（同一订单可能多次回调）。
+
+## 示例
+
+```bash
+cd python
+python3 examples/pay_create.py
+python3 examples/payout_create.py
+python3 examples/callback_verify.py   # 自演示：造签名回调 -> 验签 -> 应答 -> 篡改反例
+```
+
+## 跑测试
+
+```bash
+cd python
+python3 -m unittest discover -s tests
+```
+
+测试包含：
+
+- 读取 `../test-vectors.json`，对每个向量断言 `build_sign_base == base` 且 `sign == sign`；
+- 回调验签正例 + 篡改一字节反例（含错误密钥、缺 sign）；
+- 客户端请求构建（通用字段注入、`None` 过滤、密钥选择、`inline` 整数化、信封解析与异常分类）。

bebebus_merchant_openapi_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+bebebus_merchant_openapi_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=LRLvJ9lOPGafky5AzLCrCGsFBckxF5-mRCdHWfBLdLI,1064
+openapi_sdk/__init__.py,sha256=L6Yh_u2Q5zzzAodm1sV8chOnS0kkBzZBuDJrcdqkpjg,677
+openapi_sdk/client.py,sha256=ffoNTKR8Jf6AVh1dihyXcJ1I5gWkiSU2g37goeeoiGc,13599
+openapi_sdk/config.py,sha256=018iGLv4KqYWFMDYuRQHIlTxw2yq2GRnovxOllqkYd8,2360
+openapi_sdk/exceptions.py,sha256=fG1JGXIdLnTJZ9WkMCcuQ__9FMV2nzN-F9vGhLSheUk,1360
+openapi_sdk/signer.py,sha256=KUVwZXY6nMSG54IG-jaTxfHuyR-UsuS8JPFHwq6Jgys,3465
+bebebus_merchant_openapi_sdk-1.0.0.dist-info/METADATA,sha256=yVTVTgqr-I8E5ED9xB8IAFiYJmtxs-DcS3BYb-XMNKg,6090
+bebebus_merchant_openapi_sdk-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bebebus_merchant_openapi_sdk-1.0.0.dist-info/top_level.txt,sha256=LcgKFGNtkcmLE49DiOxUpUVMZIHIc4HlCMpGS1Goy04,12
+bebebus_merchant_openapi_sdk-1.0.0.dist-info/RECORD,,

bebebus_merchant_openapi_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bebebus_merchant_openapi_sdk-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bebebus
+
+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.

bebebus_merchant_openapi_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openapi_sdk

openapi_sdk/__init__.py

@@ -0,0 +1,31 @@
+"""商户支付 OpenAPI Python SDK（零第三方依赖）。
+
+公开 API::
+
+    from openapi_sdk import (
+        Client, Config, Environment,
+        sign, build_sign_base, verify_callback,
+        ApiError, TransportError, OpenApiError,
+    )
+"""
+
+from __future__ import annotations
+
+from .client import Client
+from .config import Config, Environment
+from .exceptions import ApiError, OpenApiError, TransportError
+from .signer import build_sign_base, sign, verify_callback
+
+__all__ = [
+    "Client",
+    "Config",
+    "Environment",
+    "sign",
+    "build_sign_base",
+    "verify_callback",
+    "ApiError",
+    "TransportError",
+    "OpenApiError",
+]
+
+__version__ = "1.0.0"

openapi_sdk/client.py

@@ -0,0 +1,374 @@
+"""商户支付 OpenAPI 客户端：覆盖全部 11 个端点。
+
+仅用标准库：urllib.request（HTTP）、json、uuid、time、secrets。
+
+约定：
+- 所有请求 POST application/json，请求体 JSON，设超时。
+- 每请求自动注入通用字段 merchant_no/api_key/timestamp/nonce。
+- 值为 None 的字段不放入请求体、也不参与签名。
+- pay 类接口用 api_secret_pay；payout 类接口用 api_secret_payout（各方法自动选对）。
+- 解析统一信封 {code, message, data}：code != 0 抛 ApiError；HTTP/网络错误抛 TransportError。
+- ``call_raw`` 暴露原始信封（code/message/data 全量），供调用方自行判断。
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Dict, List, Mapping, Optional
+
+from . import signer
+from .config import Config, Environment
+from .exceptions import ApiError, TransportError
+
+__all__ = ["Client"]
+
+_JSON_HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+    # 显式 User-Agent：urllib 默认 UA（Python-urllib/x.y）常被 WAF/CDN（如 Cloudflare）拦成 403。
+    "User-Agent": "openapi-sdk-python/1.0.0",
+}
+
+
+class Client:
+    """商户支付 OpenAPI 客户端。
+
+    用法::
+
+        from openapi_sdk import Client, Config, Environment
+        cfg = Config(
+            merchant_no="M00000001", api_key="ak_xxx",
+            api_secret_pay="sk_pay_xxx", api_secret_payout="sk_payout_xxx",
+            environment=Environment.SANDBOX,
+        )
+        client = Client(cfg)
+        resp = client.pay_create(out_order_no="ORD1", amount=10000,
+                                 currency="PHP", pay_method="gcash",
+                                 notify_url="https://m.example.com/cb")
+    """
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+
+    # ---- 便捷构造 -----------------------------------------------------------
+
+    @classmethod
+    def for_environment(
+        cls,
+        merchant_no: str,
+        api_key: str,
+        api_secret_pay: str,
+        api_secret_payout: str,
+        environment: Environment = Environment.PRODUCTION,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> "Client":
+        return cls(
+            Config(
+                merchant_no=merchant_no,
+                api_key=api_key,
+                api_secret_pay=api_secret_pay,
+                api_secret_payout=api_secret_payout,
+                environment=environment,
+                base_url=base_url,
+                timeout=timeout,
+            )
+        )
+
+    # ---- 公共属性 -----------------------------------------------------------
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    # =====================================================================
+    # 代收（Pay，密钥：api_secret_pay）
+    # =====================================================================
+
+    def pay_create(
+        self,
+        out_order_no: str,
+        amount: int,
+        currency: str,
+        pay_method: str,
+        notify_url: str,
+        country: Optional[str] = None,
+        return_url: Optional[str] = None,
+        subject: Optional[str] = None,
+        remark: Optional[str] = None,
+        client_ip: Optional[str] = None,
+        extra: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/pay/create — 代收下单。"""
+        body = {
+            "out_order_no": out_order_no,
+            "amount": amount,
+            "currency": currency,
+            "pay_method": pay_method,
+            "notify_url": notify_url,
+            "country": country,
+            "return_url": return_url,
+            "subject": subject,
+            "remark": remark,
+            "client_ip": client_ip,
+            "extra": extra,
+        }
+        return self._call_pay("/merchant/pay/create", body)
+
+    def pay_query(
+        self,
+        order_no: Optional[str] = None,
+        out_order_no: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/pay/query — 代收查单（order_no / out_order_no 二选一）。"""
+        return self._call_pay(
+            "/merchant/pay/query",
+            {"order_no": order_no, "out_order_no": out_order_no},
+        )
+
+    def pay_methods_query(self, country: Optional[str] = None) -> Dict[str, Any]:
+        """POST /merchant/pay-methods/query — 可用支付方式。"""
+        return self._call_pay("/merchant/pay-methods/query", {"country": country})
+
+    def balance_query(self, currency: Optional[str] = None) -> Dict[str, Any]:
+        """POST /merchant/balance/query — 余额查询。"""
+        return self._call_pay("/merchant/balance/query", {"currency": currency})
+
+    def pay_test_complete(
+        self,
+        result: str,
+        order_no: Optional[str] = None,
+        out_order_no: Optional[str] = None,
+        actual_amount: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/pay/test/complete — 代收测试单完成（仅测试密钥）。"""
+        return self._call_pay(
+            "/merchant/pay/test/complete",
+            {
+                "order_no": order_no,
+                "out_order_no": out_order_no,
+                "result": result,
+                "actual_amount": actual_amount,
+            },
+        )
+
+    # =====================================================================
+    # 代付（Payout，密钥：api_secret_payout）
+    # =====================================================================
+
+    def payout_create(
+        self,
+        out_payout_no: str,
+        amount: int,
+        currency: str,
+        pay_method: str,
+        notify_url: str,
+        account_no: str,
+        country: Optional[str] = None,
+        account_name: Optional[str] = None,
+        bank_code: Optional[str] = None,
+        bank_name: Optional[str] = None,
+        remark: Optional[str] = None,
+        client_ip: Optional[str] = None,
+        extra: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/payout/create — 代付下单。"""
+        body = {
+            "out_payout_no": out_payout_no,
+            "amount": amount,
+            "currency": currency,
+            "pay_method": pay_method,
+            "notify_url": notify_url,
+            "account_no": account_no,
+            "country": country,
+            "account_name": account_name,
+            "bank_code": bank_code,
+            "bank_name": bank_name,
+            "remark": remark,
+            "client_ip": client_ip,
+            "extra": extra,
+        }
+        return self._call_payout("/merchant/payout/create", body)
+
+    def payout_query(
+        self,
+        payout_no: Optional[str] = None,
+        out_payout_no: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/payout/query — 代付查单（payout_no / out_payout_no 二选一）。"""
+        return self._call_payout(
+            "/merchant/payout/query",
+            {"payout_no": payout_no, "out_payout_no": out_payout_no},
+        )
+
+    def payout_banks_query(
+        self,
+        pay_method: str,
+        country: Optional[str] = None,
+        currency: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/payout/banks/query — 可用银行。"""
+        return self._call_payout(
+            "/merchant/payout/banks/query",
+            {"pay_method": pay_method, "country": country, "currency": currency},
+        )
+
+    def payout_proof_query(
+        self,
+        payout_no: Optional[str] = None,
+        out_payout_no: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/payout/proof/query — 代付凭证查询（仅 success 可查）。"""
+        return self._call_payout(
+            "/merchant/payout/proof/query",
+            {"payout_no": payout_no, "out_payout_no": out_payout_no},
+        )
+
+    def payout_receipt_query(
+        self,
+        payout_no: Optional[str] = None,
+        out_payout_no: Optional[str] = None,
+        lang: Optional[str] = None,
+        inline: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/payout/receipt/query — 代付收据。
+
+        ``inline`` 以整数 1/0 发送（避免布尔跨语言签名歧义）：
+        ``True``->1 内联返回 base64 图片；``False``->0 / 省略 返回带 token 的 URL。
+        """
+        inline_int = None if inline is None else (1 if inline else 0)
+        return self._call_payout(
+            "/merchant/payout/receipt/query",
+            {
+                "payout_no": payout_no,
+                "out_payout_no": out_payout_no,
+                "lang": lang,
+                "inline": inline_int,
+            },
+        )
+
+    def payout_test_complete(
+        self,
+        result: str,
+        payout_no: Optional[str] = None,
+        out_payout_no: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /merchant/payout/test/complete — 代付测试单完成（仅测试密钥）。"""
+        return self._call_payout(
+            "/merchant/payout/test/complete",
+            {
+                "payout_no": payout_no,
+                "out_payout_no": out_payout_no,
+                "result": result,
+            },
+        )
+
+    # =====================================================================
+    # 内部：请求构建 / 发送 / 解析
+    # =====================================================================
+
+    def _call_pay(self, path: str, body: Mapping[str, Any]) -> Dict[str, Any]:
+        return self._call(path, body, self._config.api_secret_pay)
+
+    def _call_payout(self, path: str, body: Mapping[str, Any]) -> Dict[str, Any]:
+        return self._call(path, body, self._config.api_secret_payout)
+
+    def call_raw(
+        self, path: str, body: Mapping[str, Any], secret: str
+    ) -> Dict[str, Any]:
+        """发起请求并返回**原始统一信封**（不因 code != 0 抛 ApiError）。
+
+        仍会对 HTTP / 网络 / JSON 解析失败抛 TransportError。
+        供调用方需要自行处理 code 时使用。
+        """
+        envelope = self._request(path, body, secret)
+        return envelope
+
+    def _call(self, path: str, body: Mapping[str, Any], secret: str) -> Dict[str, Any]:
+        envelope = self._request(path, body, secret)
+        code = envelope.get("code")
+        if code != 0:
+            raise ApiError(
+                code=code if isinstance(code, int) else -1,
+                message=str(envelope.get("message", "")),
+                data=envelope.get("data"),
+            )
+        data = envelope.get("data")
+        return data if isinstance(data, dict) else {}
+
+    def _build_payload(
+        self, body: Mapping[str, Any], secret: str
+    ) -> Dict[str, Any]:
+        """注入通用字段、剔除 None、计算签名，返回最终请求体。"""
+        payload: Dict[str, Any] = {}
+        for k, v in body.items():
+            if v is not None:
+                payload[k] = v
+        # 通用字段由 SDK 统一注入，且**始终覆盖**调用方同名字段（跨语言一致语义）。
+        payload["merchant_no"] = self._config.merchant_no
+        payload["api_key"] = self._config.api_key
+        payload["timestamp"] = int(time.time())
+        payload["nonce"] = self._gen_nonce()
+        payload["sign"] = signer.sign(payload, secret)
+        return payload
+
+    @staticmethod
+    def _gen_nonce() -> str:
+        """每请求唯一 nonce：UUID4 + 随机 hex，碰撞概率可忽略。"""
+        return uuid.uuid4().hex + secrets.token_hex(8)
+
+    def _request(
+        self, path: str, body: Mapping[str, Any], secret: str
+    ) -> Dict[str, Any]:
+        payload = self._build_payload(body, secret)
+        url = self._config.base_url + path
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        request = urllib.request.Request(
+            url, data=data, headers=dict(_JSON_HEADERS), method="POST"
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=self._config.timeout) as resp:
+                status = resp.getcode()
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:  # 非 2xx
+            raw_body = None
+            try:
+                raw_body = exc.read().decode("utf-8")
+            except Exception:  # noqa: BLE001 - 读取错误体本身失败时忽略
+                pass
+            raise TransportError(
+                f"HTTP {exc.code} 请求失败: {url}",
+                status_code=exc.code,
+                body=raw_body,
+                cause=exc,
+            ) from exc
+        except urllib.error.URLError as exc:  # DNS/连接/超时
+            raise TransportError(
+                f"网络请求失败: {url} ({exc.reason})", cause=exc
+            ) from exc
+        except Exception as exc:  # noqa: BLE001 - 其余 IO/超时
+            raise TransportError(f"请求异常: {url} ({exc})", cause=exc) from exc
+
+        try:
+            envelope = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise TransportError(
+                f"响应非合法 JSON: {url}",
+                status_code=status,
+                body=raw,
+                cause=exc,
+            ) from exc
+
+        if not isinstance(envelope, dict) or "code" not in envelope:
+            raise TransportError(
+                f"响应缺少统一信封字段(code): {url}",
+                status_code=status,
+                body=raw,
+            )
+        return envelope

openapi_sdk/config.py

@@ -0,0 +1,71 @@
+"""环境与客户端配置。
+
+- ``Environment``：预设环境枚举（PRODUCTION / SANDBOX）。
+- ``Config``：商户号 + API Key + 双密钥 + 基址 + 超时。
+
+正式环境（PRODUCTION）没有内置基址：真实地址按上级代理专有域名派生
+（``https://api.<agent_domain>/api/open/v1``），必须显式传入 ``base_url``。
+沙箱（SANDBOX）保留本地预设基址，便于本地联调。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+__all__ = ["Environment", "Config"]
+
+
+class Environment(Enum):
+    """预设环境。
+
+    - ``PRODUCTION``：无内置基址（空字符串），必须显式传 ``base_url``。
+    - ``SANDBOX``：本地预设基址。
+    """
+
+    PRODUCTION = ""
+    SANDBOX = "http://127.0.0.1:3090/api/open/v1"
+
+    @property
+    def base_url(self) -> str:
+        return self.value
+
+
+class Config:
+    """客户端配置。
+
+    密钥分两套：``api_secret_pay`` 用于 pay 类接口与代收/退款回调；
+    ``api_secret_payout`` 用于 payout 类接口与代付回调。客户端各方法自动选对密钥。
+
+    基址优先级：显式 ``base_url`` > ``environment`` 预设。``base_url`` 末尾斜杠会被去除。
+    若最终基址为空（如选了 PRODUCTION 又未传 ``base_url``）则抛 ``ValueError``。
+    """
+
+    def __init__(
+        self,
+        merchant_no: str,
+        api_key: str,
+        api_secret_pay: str,
+        api_secret_payout: str,
+        environment: Environment = Environment.PRODUCTION,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        if not merchant_no:
+            raise ValueError("merchant_no 不能为空")
+        if not api_key:
+            raise ValueError("api_key 不能为空")
+
+        self.merchant_no = merchant_no
+        self.api_key = api_key
+        self.api_secret_pay = api_secret_pay
+        self.api_secret_payout = api_secret_payout
+        self.environment = environment
+        resolved = base_url if base_url else environment.base_url
+        if not resolved:
+            raise ValueError(
+                "baseUrl is required: production base URL is provided per your "
+                "agent domain (e.g. https://api.<agent_domain>/api/open/v1)"
+            )
+        self.base_url = resolved.rstrip("/")
+        self.timeout = timeout

openapi_sdk/exceptions.py

@@ -0,0 +1,46 @@
+"""SDK 异常类型。
+
+- ``ApiError``：业务失败（统一信封 ``code != 0``），携带 code/message/data。
+- ``TransportError``：HTTP 状态非 2xx、网络错误、超时、响应非合法 JSON 等传输层问题。
+
+二者均继承自 ``OpenApiError``，调用方可只捕获基类。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+__all__ = ["OpenApiError", "ApiError", "TransportError"]
+
+
+class OpenApiError(Exception):
+    """SDK 异常基类。"""
+
+
+class ApiError(OpenApiError):
+    """业务异常：统一响应信封中 ``code != 0``。
+
+    携带原始 ``code``/``message``/``data`` 供调用方判断，不在 SDK 内穷举写死分支。
+    """
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        super().__init__(f"[{code}] {message}")
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+class TransportError(OpenApiError):
+    """传输异常：HTTP 非 2xx、网络错误、超时、响应不可解析为 JSON 等。"""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        body: Optional[str] = None,
+        cause: Optional[BaseException] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.cause = cause

openapi_sdk/signer.py

@@ -0,0 +1,95 @@
+"""签名器：HMAC-SHA256 -> 十六进制小写。
+
+与服务端签名实现逐字节一致。
+算法权威定义见 ../SIGNING.md，可复现 ../test-vectors.json 的 base 与 sign。
+
+仅用 Python 标准库：json / hmac / hashlib。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any, Dict, Mapping
+
+__all__ = ["build_sign_base", "sign", "verify_callback"]
+
+
+def _stable_stringify(value: Any) -> str:
+    """嵌套 object/array 的稳定 JSON 序列化，对齐 JS ``JSON.stringify`` + key 升序。
+
+    - ``ensure_ascii=False``：非 ASCII（中文/emoji）原样保留，不转 ``\\uXXXX``。
+    - ``separators=(',', ':')``：紧凑无空格。
+    - ``sort_keys=True``：对象 key 递归升序。
+
+    Python ``json.dumps`` 不转义 ``/`` 与 ``<>&``，与 JS 默认行为一致；
+    会转义 ``"`` ``\\`` 及控制字符（``\\b\\f\\n\\r\\t`` 与其余 ``\\u00XX``），亦与 JS 一致。
+    """
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def _value_for_sign(v: Any) -> str:
+    """单字段取值的字符串形态（不加引号）。
+
+    - object / array -> 稳定 JSON 序列化。
+    - 标量 -> 原始字符串形态。
+
+    关键坑：必须先判 ``bool`` 再判 ``int``（``bool`` 是 ``int`` 子类），
+    且布尔须归一为 ``true``/``false``（``str(True) == "True"`` 是错的）。
+    """
+    if v is None:
+        # 调用方在 build_sign_base 已过滤 None；此处兜底，与服务端 null 一致。
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (dict, list)):
+        return _stable_stringify(v)
+    # 其余标量（int / str / float），用原始字符串形态、不加引号。
+    return str(v)
+
+
+def build_sign_base(payload: Mapping[str, Any], secret: str) -> str:
+    """构造签名 base 字符串（不计算 HMAC，便于逐字节断言）。
+
+    步骤：
+    1. 过滤掉键名为 ``sign`` 的字段，以及值为 ``None`` 的字段。
+    2. 剩余字段按键名 ASCII（码点）升序排序。
+    3. 每个字段拼成 ``key=value``，用 ``&`` 连接。
+    4. 末尾追加 ``&secret=<secret>``。
+    """
+    keys = sorted(k for k, v in payload.items() if k != "sign" and v is not None)
+    parts = [f"{k}={_value_for_sign(payload[k])}" for k in keys]
+    parts.append(f"secret={secret}")
+    return "&".join(parts)
+
+
+def sign(payload: Mapping[str, Any], secret: str) -> str:
+    """对 payload 计算签名，返回十六进制小写字符串。"""
+    base = build_sign_base(payload, secret)
+    return hmac.new(
+        secret.encode("utf-8"),
+        base.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def verify_callback(payload: Mapping[str, Any], secret: str) -> bool:
+    """回调验签（字段无关、时序安全）。
+
+    取回调表里除 ``sign`` 外的所有字段，用本算法算出期望签名，
+    与回调携带的 ``sign`` 做时序安全比较（``hmac.compare_digest``）。
+
+    代收/退款回调用 ``api_secret_pay``；代付回调用 ``api_secret_payout``。
+    """
+    provided = payload.get("sign")
+    if not isinstance(provided, str) or not provided:
+        return False
+    # build_sign_base 自身已排除 sign 字段，无需事先剔除。
+    expected = sign(payload, secret)
+    return hmac.compare_digest(expected, provided)