showmac-pay 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ShowMac
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,113 @@
1
+ Metadata-Version: 2.4
2
+ Name: showmac-pay
3
+ Version: 1.0.0
4
+ Summary: ShowMac 支付网关 Python 客户端(零第三方依赖)
5
+ Author: ShowMac
6
+ Keywords: showmac,payment,pay,sdk
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Operating System :: OS Independent
9
+ Requires-Python: >=3.8
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest>=7; extra == "dev"
14
+ Dynamic: license-file
15
+
16
+ # showmac-pay(Python)
17
+
18
+ ShowMac 支付网关的 Python 客户端。**零第三方依赖**,只用标准库,Python 3.8+。
19
+
20
+ ```bash
21
+ pip install ./sdk/python # 从本仓库安装(当前尚未发布到 PyPI)
22
+ ```
23
+
24
+ > 也可以只把 `sdk/python/src/showmac_pay` 整个目录拷进项目直接 import。
25
+ > 若日后发布到 PyPI,安装命令为 `pip install showmac-pay`。
26
+
27
+ ## 快速开始
28
+
29
+ ```python
30
+ import os
31
+ import time
32
+
33
+ from showmac_pay import PayError, ShowMacPay
34
+
35
+ client = ShowMacPay(
36
+ mch_no="M1621873433953",
37
+ app_id="60cc09bce4b0f1c0b83761c9",
38
+ api_key=os.environ["SHOWMAC_PAY_API_KEY"], # 应用密钥,不要硬编码
39
+ api_base="https://<支付网关域名>",
40
+ )
41
+
42
+ order = client.unified_order(
43
+ mch_order_no="mho" + str(int(time.time() * 1000)),
44
+ way_code="WX_NATIVE",
45
+ amount=100, # 单位:分,必须是整数
46
+ subject="商品标题",
47
+ body="商品描述",
48
+ notify_url="https://your-domain.com/notify/pay",
49
+ return_url="https://your-domain.com/pay/result",
50
+ channel_extra={"payDataType": "codeImgUrl"}, # 需要时传,内部会自动转 JSON
51
+ )
52
+
53
+ print(order["payOrderId"], order["payDataType"], order["payData"])
54
+ ```
55
+
56
+ 其余接口:
57
+
58
+ ```python
59
+ client.query_order(mch_order_no="mho1") # 或 pay_order_id=...
60
+ client.close_order(pay_order_id="P...")
61
+ client.refund(mch_refund_no="r1", refund_amount=100,
62
+ refund_reason="用户取消", pay_order_id="P...") # currency 默认 CNY
63
+ client.query_refund(mch_refund_no="r1")
64
+ ```
65
+
66
+ ## 异步通知
67
+
68
+ 网关用 **form 表单** POST 通知,接收方要做的三件事:验签 → 幂等 → 返回 `success`。
69
+
70
+ FastAPI 示例(Flask / Django 同理,关键是取 form 参数而不是 JSON body):
71
+
72
+ ```python
73
+ from fastapi import FastAPI, Request, Response
74
+
75
+ from showmac_pay import is_paid, order_no_of, verify_notify
76
+
77
+ app = FastAPI()
78
+
79
+
80
+ @app.post("/notify/pay")
81
+ async def notify(request: Request):
82
+ params = dict(await request.form())
83
+
84
+ try:
85
+ params = verify_notify(params, API_KEY) # 验签 + 必填字段校验
86
+ except ValueError as exc:
87
+ log.warning("通知被拒: %s", exc)
88
+ return Response("fail", media_type="text/plain")
89
+
90
+ if is_paid(params) and not already_processed(order_no_of(params)):
91
+ mark_paid(params) # 用唯一索引保证幂等
92
+
93
+ return Response("success", media_type="text/plain")
94
+ ```
95
+
96
+ `verify_notify` 除了验签,还会检查 `mchOrderNo` 非空——因为签名算法会过滤空值,
97
+ **只带 `sign` 的空报文也能算出合法签名**,只看签名等于放行空通知。
98
+
99
+ ## 行为说明
100
+
101
+ - 请求固定 `POST` + `application/json`,自动注入 `mchNo` / `appId` / `version` /
102
+ `signType` / `reqTime` / `sign`,这六个字段**不要自己再传**。
103
+ - 响应 `sign` 只覆盖 `data`(不含 `code`/`msg`),默认校验;关掉等于放弃防伪造。
104
+ - 业务失败抛 `PayError`(`.code` / `.msg` / `.raw`),响应验签失败抛 `SignatureError`。
105
+ - `amount` / `refund_amount` 会自动 `int()`:网关端是 `Long`,传浮点必然验签失败。
106
+ - 多商户:每个商户各建一个 `ShowMacPay` 实例。**不要**用全局配置(官方 Python SDK
107
+ 就是全局的,并发下会串商户)。
108
+
109
+ ## 开发
110
+
111
+ ```bash
112
+ python -m pytest # 22 个用例,含跨语言签名向量
113
+ ```
@@ -0,0 +1,98 @@
1
+ # showmac-pay(Python)
2
+
3
+ ShowMac 支付网关的 Python 客户端。**零第三方依赖**,只用标准库,Python 3.8+。
4
+
5
+ ```bash
6
+ pip install ./sdk/python # 从本仓库安装(当前尚未发布到 PyPI)
7
+ ```
8
+
9
+ > 也可以只把 `sdk/python/src/showmac_pay` 整个目录拷进项目直接 import。
10
+ > 若日后发布到 PyPI,安装命令为 `pip install showmac-pay`。
11
+
12
+ ## 快速开始
13
+
14
+ ```python
15
+ import os
16
+ import time
17
+
18
+ from showmac_pay import PayError, ShowMacPay
19
+
20
+ client = ShowMacPay(
21
+ mch_no="M1621873433953",
22
+ app_id="60cc09bce4b0f1c0b83761c9",
23
+ api_key=os.environ["SHOWMAC_PAY_API_KEY"], # 应用密钥,不要硬编码
24
+ api_base="https://<支付网关域名>",
25
+ )
26
+
27
+ order = client.unified_order(
28
+ mch_order_no="mho" + str(int(time.time() * 1000)),
29
+ way_code="WX_NATIVE",
30
+ amount=100, # 单位:分,必须是整数
31
+ subject="商品标题",
32
+ body="商品描述",
33
+ notify_url="https://your-domain.com/notify/pay",
34
+ return_url="https://your-domain.com/pay/result",
35
+ channel_extra={"payDataType": "codeImgUrl"}, # 需要时传,内部会自动转 JSON
36
+ )
37
+
38
+ print(order["payOrderId"], order["payDataType"], order["payData"])
39
+ ```
40
+
41
+ 其余接口:
42
+
43
+ ```python
44
+ client.query_order(mch_order_no="mho1") # 或 pay_order_id=...
45
+ client.close_order(pay_order_id="P...")
46
+ client.refund(mch_refund_no="r1", refund_amount=100,
47
+ refund_reason="用户取消", pay_order_id="P...") # currency 默认 CNY
48
+ client.query_refund(mch_refund_no="r1")
49
+ ```
50
+
51
+ ## 异步通知
52
+
53
+ 网关用 **form 表单** POST 通知,接收方要做的三件事:验签 → 幂等 → 返回 `success`。
54
+
55
+ FastAPI 示例(Flask / Django 同理,关键是取 form 参数而不是 JSON body):
56
+
57
+ ```python
58
+ from fastapi import FastAPI, Request, Response
59
+
60
+ from showmac_pay import is_paid, order_no_of, verify_notify
61
+
62
+ app = FastAPI()
63
+
64
+
65
+ @app.post("/notify/pay")
66
+ async def notify(request: Request):
67
+ params = dict(await request.form())
68
+
69
+ try:
70
+ params = verify_notify(params, API_KEY) # 验签 + 必填字段校验
71
+ except ValueError as exc:
72
+ log.warning("通知被拒: %s", exc)
73
+ return Response("fail", media_type="text/plain")
74
+
75
+ if is_paid(params) and not already_processed(order_no_of(params)):
76
+ mark_paid(params) # 用唯一索引保证幂等
77
+
78
+ return Response("success", media_type="text/plain")
79
+ ```
80
+
81
+ `verify_notify` 除了验签,还会检查 `mchOrderNo` 非空——因为签名算法会过滤空值,
82
+ **只带 `sign` 的空报文也能算出合法签名**,只看签名等于放行空通知。
83
+
84
+ ## 行为说明
85
+
86
+ - 请求固定 `POST` + `application/json`,自动注入 `mchNo` / `appId` / `version` /
87
+ `signType` / `reqTime` / `sign`,这六个字段**不要自己再传**。
88
+ - 响应 `sign` 只覆盖 `data`(不含 `code`/`msg`),默认校验;关掉等于放弃防伪造。
89
+ - 业务失败抛 `PayError`(`.code` / `.msg` / `.raw`),响应验签失败抛 `SignatureError`。
90
+ - `amount` / `refund_amount` 会自动 `int()`:网关端是 `Long`,传浮点必然验签失败。
91
+ - 多商户:每个商户各建一个 `ShowMacPay` 实例。**不要**用全局配置(官方 Python SDK
92
+ 就是全局的,并发下会串商户)。
93
+
94
+ ## 开发
95
+
96
+ ```bash
97
+ python -m pytest # 22 个用例,含跨语言签名向量
98
+ ```
@@ -0,0 +1,26 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "showmac-pay"
7
+ version = "1.0.0"
8
+ description = "ShowMac 支付网关 Python 客户端(零第三方依赖)"
9
+ readme = "README.md"
10
+ requires-python = ">=3.8"
11
+ authors = [{ name = "ShowMac" }]
12
+ keywords = ["showmac", "payment", "pay", "sdk"]
13
+ classifiers = [
14
+ "Programming Language :: Python :: 3",
15
+ "Operating System :: OS Independent",
16
+ ]
17
+ dependencies = []
18
+
19
+ [project.optional-dependencies]
20
+ dev = ["pytest>=7"]
21
+
22
+ [tool.setuptools.packages.find]
23
+ where = ["src"]
24
+
25
+ [tool.pytest.ini_options]
26
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,40 @@
1
+ """ShowMac 支付网关 Python 客户端。
2
+
3
+ 按网关的公开 HTTP 接口规范实现,不引入任何第三方依赖。
4
+
5
+ from showmac_pay import ShowMacPay
6
+
7
+ client = ShowMacPay(
8
+ mch_no="M1621873433953",
9
+ app_id="60cc09bce4b0f1c0b83761c9",
10
+ api_key=os.environ["SHOWMAC_PAY_API_KEY"],
11
+ api_base="https://pay.example.com",
12
+ )
13
+ order = client.unified_order(
14
+ mch_order_no="mho" + str(int(time.time())),
15
+ way_code="WX_NATIVE",
16
+ amount=100,
17
+ subject="商品标题",
18
+ body="商品描述",
19
+ notify_url="https://your-domain.com/notify/pay",
20
+ )
21
+ """
22
+
23
+ from .client import ShowMacPay
24
+ from .exceptions import NotifyError, PayError, SignatureError
25
+ from .notify import order_no_of, verify_notify
26
+ from .sign import sign, sign_str, verify
27
+
28
+ __all__ = [
29
+ "ShowMacPay",
30
+ "PayError",
31
+ "SignatureError",
32
+ "NotifyError",
33
+ "sign",
34
+ "sign_str",
35
+ "verify",
36
+ "verify_notify",
37
+ "order_no_of",
38
+ ]
39
+
40
+ __version__ = "1.0.0"
@@ -0,0 +1,212 @@
1
+ """HTTP 客户端。仅用标准库(urllib),不依赖 requests。
2
+
3
+ 请求构造遵循网关的 HTTP 接口规范:
4
+ POST + ``application/json``,body 里带上 version / signType / reqTime / sign。
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import time
11
+ import urllib.error
12
+ import urllib.request
13
+ from typing import Any, Dict, Mapping, Optional
14
+
15
+ from .exceptions import PayError, SignatureError
16
+ from .sign import sign
17
+
18
+ API_VERSION = "1.0"
19
+ SIGN_TYPE = "MD5"
20
+
21
+ # 与 Java SDK 的 RequestOptions 默认值保持一致
22
+ DEFAULT_TIMEOUT = 20.0
23
+ DEFAULT_HEADERS = {
24
+ "Content-Type": "application/json; charset=UTF-8",
25
+ "Accept": "application/json",
26
+ "Accept-Charset": "UTF-8",
27
+ "Accept-Language": "zh-CN",
28
+ }
29
+
30
+
31
+ class ShowMacPay:
32
+ """支付网关客户端。每个商户/应用一个实例,不要用全局可变配置。
33
+
34
+ :param mch_no: 商户号
35
+ :param app_id: 应用 ID
36
+ :param api_key: 应用密钥(网关侧叫 appSecret)
37
+ :param api_base: 网关地址,如 ``https://pay.example.com``
38
+ :param timeout: 单次请求超时(秒)
39
+ :param verify_response: 是否校验响应签名。**生产环境务必保持 True**,
40
+ 关掉等于放弃防伪造能力。
41
+ """
42
+
43
+ def __init__(self, mch_no: str, app_id: str, api_key: str, api_base: str,
44
+ timeout: float = DEFAULT_TIMEOUT,
45
+ verify_response: bool = True,
46
+ user_agent: str = "showmac-pay-python/1.0.0") -> None:
47
+ if not mch_no or not app_id or not api_key:
48
+ raise ValueError("mch_no / app_id / api_key 均不能为空")
49
+ if not api_base:
50
+ raise ValueError("api_base 不能为空")
51
+ self.mch_no = mch_no
52
+ self.app_id = app_id
53
+ self.api_key = api_key
54
+ self.api_base = api_base.rstrip("/")
55
+ self.timeout = timeout
56
+ self.verify_response = verify_response
57
+ self.user_agent = user_agent
58
+
59
+ # ------------------------------------------------------------ 底层 HTTP
60
+
61
+ def _post(self, uri: str, biz: Mapping[str, Any]) -> Dict[str, Any]:
62
+ """发请求并把响应里的 ``data`` 返回;业务失败抛 :class:`PayError`。"""
63
+ params: Dict[str, Any] = {
64
+ k: v for k, v in biz.items() if v is not None and v != ""
65
+ }
66
+ params["mchNo"] = self.mch_no
67
+ params["appId"] = self.app_id
68
+ params["version"] = API_VERSION
69
+ params["signType"] = SIGN_TYPE
70
+ params["reqTime"] = str(int(time.time() * 1000))
71
+ params["sign"] = sign(params, self.api_key)
72
+
73
+ payload = json.dumps(params, ensure_ascii=False,
74
+ separators=(",", ":")).encode("utf-8")
75
+ headers = dict(DEFAULT_HEADERS, **{"User-Agent": self.user_agent})
76
+ request = urllib.request.Request(
77
+ f"{self.api_base}/{uri.lstrip('/')}",
78
+ data=payload, headers=headers, method="POST",
79
+ )
80
+
81
+ try:
82
+ with urllib.request.urlopen(request, timeout=self.timeout) as resp:
83
+ body = resp.read().decode("utf-8")
84
+ status = resp.status
85
+ except urllib.error.HTTPError as exc:
86
+ detail = exc.read().decode("utf-8", "ignore")[:500]
87
+ raise PayError(None, f"HTTP {exc.code}: {detail}") from exc
88
+ except urllib.error.URLError as exc:
89
+ raise PayError(None, f"网络异常: {exc.reason}") from exc
90
+
91
+ try:
92
+ result = json.loads(body)
93
+ except json.JSONDecodeError as exc:
94
+ raise PayError(None, f"响应不是合法 JSON (HTTP {status}): {body[:200]}") from exc
95
+
96
+ code = result.get("code")
97
+ if code != 0:
98
+ raise PayError(code if isinstance(code, int) else None,
99
+ result.get("msg") or "未知错误", result)
100
+
101
+ self._check_response_sign(result)
102
+ return result.get("data") or {}
103
+
104
+ def _check_response_sign(self, result: Mapping[str, Any]) -> None:
105
+ """响应里的 sign 只覆盖 ``data``,不含 code/msg。"""
106
+ if not self.verify_response:
107
+ return
108
+ data = result.get("data")
109
+ resp_sign = result.get("sign")
110
+ if data is None:
111
+ if resp_sign:
112
+ raise SignatureError(0, "响应 data 为空但存在 sign,报文异常", result)
113
+ return
114
+ expected = sign(data, self.api_key) # type: ignore[arg-type]
115
+ if str(resp_sign or "").upper() != expected:
116
+ raise SignatureError(
117
+ 0, f"响应验签失败: 收到 {resp_sign} 本地 {expected}", result)
118
+
119
+ # ------------------------------------------------------------ 业务接口
120
+
121
+ def unified_order(self, *, mch_order_no: str, way_code: str, amount: int,
122
+ subject: str, body: str,
123
+ client_ip: str = "127.0.0.1", currency: str = "CNY",
124
+ notify_url: Optional[str] = None,
125
+ return_url: Optional[str] = None,
126
+ expired_time: Optional[int] = None,
127
+ channel_extra: Optional[Mapping[str, Any]] = None,
128
+ ext_param: Optional[str] = None,
129
+ division_mode: Optional[int] = None) -> Dict[str, Any]:
130
+ """统一下单。``amount`` 单位:分。
131
+
132
+ ``channel_extra`` 传字典即可,内部会序列化成紧凑 JSON 字符串参与签名
133
+ (引号原样保留,不做 URL 编码)。
134
+ """
135
+ biz: Dict[str, Any] = {
136
+ "mchOrderNo": mch_order_no,
137
+ "wayCode": way_code,
138
+ "amount": int(amount),
139
+ "currency": currency,
140
+ "clientIp": client_ip,
141
+ "subject": subject,
142
+ "body": body,
143
+ "notifyUrl": notify_url,
144
+ "returnUrl": return_url,
145
+ "expiredTime": expired_time,
146
+ "extParam": ext_param,
147
+ "divisionMode": division_mode,
148
+ }
149
+ if channel_extra is not None:
150
+ biz["channelExtra"] = json.dumps(
151
+ channel_extra, ensure_ascii=False, separators=(",", ":"))
152
+ return self._post("api/pay/unifiedOrder", biz)
153
+
154
+ def query_order(self, *, mch_order_no: Optional[str] = None,
155
+ pay_order_id: Optional[str] = None) -> Dict[str, Any]:
156
+ """查询支付订单。两个单号至少传一个。"""
157
+ self._require_one(mch_order_no=mch_order_no, pay_order_id=pay_order_id)
158
+ return self._post("api/pay/query",
159
+ {"mchOrderNo": mch_order_no, "payOrderId": pay_order_id})
160
+
161
+ def close_order(self, *, mch_order_no: Optional[str] = None,
162
+ pay_order_id: Optional[str] = None) -> Dict[str, Any]:
163
+ """关闭支付订单。"""
164
+ self._require_one(mch_order_no=mch_order_no, pay_order_id=pay_order_id)
165
+ return self._post("api/pay/close",
166
+ {"mchOrderNo": mch_order_no, "payOrderId": pay_order_id})
167
+
168
+ def refund(self, *, mch_refund_no: str, refund_amount: int,
169
+ refund_reason: str,
170
+ mch_order_no: Optional[str] = None,
171
+ pay_order_id: Optional[str] = None,
172
+ currency: str = "CNY", client_ip: str = "127.0.0.1",
173
+ notify_url: Optional[str] = None,
174
+ channel_extra: Optional[Mapping[str, Any]] = None,
175
+ ext_param: Optional[str] = None) -> Dict[str, Any]:
176
+ """发起退款。``refund_amount`` 单位:分。
177
+
178
+ 注意 ``currency`` 与 ``refund_reason`` 在网关侧是必填(``@NotBlank``),
179
+ 漏传会返回「货币代码不能为空」「退款原因不能为空」,与签名无关。
180
+ """
181
+ self._require_one(mch_order_no=mch_order_no, pay_order_id=pay_order_id)
182
+ biz: Dict[str, Any] = {
183
+ "mchRefundNo": mch_refund_no,
184
+ "refundAmount": int(refund_amount),
185
+ "currency": currency,
186
+ "refundReason": refund_reason,
187
+ "clientIp": client_ip,
188
+ "mchOrderNo": mch_order_no,
189
+ "payOrderId": pay_order_id,
190
+ "notifyUrl": notify_url,
191
+ "extParam": ext_param,
192
+ }
193
+ if channel_extra is not None:
194
+ biz["channelExtra"] = json.dumps(
195
+ channel_extra, ensure_ascii=False, separators=(",", ":"))
196
+ return self._post("api/refund/refundOrder", biz)
197
+
198
+ def query_refund(self, *, mch_refund_no: Optional[str] = None,
199
+ refund_order_id: Optional[str] = None) -> Dict[str, Any]:
200
+ """查询退款订单。"""
201
+ self._require_one(mch_refund_no=mch_refund_no,
202
+ refund_order_id=refund_order_id)
203
+ return self._post("api/refund/query", {
204
+ "mchRefundNo": mch_refund_no,
205
+ "refundOrderId": refund_order_id,
206
+ })
207
+
208
+ @staticmethod
209
+ def _require_one(**kwargs: Any) -> None:
210
+ if not any(v for v in kwargs.values()):
211
+ names = " / ".join(kwargs)
212
+ raise ValueError(f"{names} 至少传一个")
@@ -0,0 +1,30 @@
1
+ """异常定义。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Optional
6
+
7
+
8
+ class PayError(Exception):
9
+ """调用网关失败。
10
+
11
+ code 为网关业务码(0 表示成功,非 0 表示业务失败);网络异常、HTTP 异常时 code 为 None。
12
+ raw 保留网关原始响应,便于排查。
13
+ """
14
+
15
+ def __init__(self, code: Optional[int], msg: str, raw: Any = None) -> None:
16
+ super().__init__(f"[{code}] {msg}")
17
+ self.code = code
18
+ self.msg = msg
19
+ self.raw = raw
20
+
21
+
22
+ class SignatureError(PayError):
23
+ """签名相关失败:请求构造异常,或响应/通知验签不通过。"""
24
+
25
+
26
+ class NotifyError(ValueError):
27
+ """异步通知不合法(缺签名、验签失败、缺必填字段)。
28
+
29
+ 继承 ``ValueError``,所以 ``except ValueError`` 也能捕获,方便在框架里统一处理。
30
+ """
@@ -0,0 +1,50 @@
1
+ """异步通知处理。
2
+
3
+ 网关的通知是用 **form 表单** POST 的,参数与签名算法和请求完全一致,用同一个 apiKey。
4
+ 接收方必须做三件事:验签 -> 幂等 -> 返回 ``success``。
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Any, Dict, Mapping, Optional, Tuple
10
+
11
+ from .exceptions import NotifyError
12
+ from .sign import verify
13
+
14
+ # 订单状态:与网关 CS.PAY_ORDER_STATE 一致
15
+ STATE_ING = "1"
16
+ STATE_PAY_SUCCESS = "2"
17
+ STATE_FAIL = "3"
18
+ STATE_CANCEL = "4"
19
+ STATE_REFUND = "5"
20
+ STATE_CLOSED = "6"
21
+
22
+
23
+ def verify_notify(params: Mapping[str, Any], api_key: str,
24
+ required: Tuple[str, ...] = ("mchOrderNo",)) -> Dict[str, Any]:
25
+ """校验通知并返回参数副本;不合法时抛 :class:`NotifyError`,调用方应返回 ``fail``。
26
+
27
+ 为什么验签之后还要查 ``required``:签名算法会过滤空值,**只带 sign 的空报文**
28
+ 也能算出合法签名(等价于对 ``key=<apiKey>`` 求 MD5)。只看签名等于放行空通知。
29
+ """
30
+ body: Dict[str, Any] = dict(params)
31
+
32
+ if not str(body.get("sign") or "").strip():
33
+ raise NotifyError("通知缺少 sign")
34
+ if not verify(body, api_key):
35
+ raise NotifyError("通知验签失败")
36
+ for field in required:
37
+ if not str(body.get(field) or "").strip():
38
+ raise NotifyError(f"通知缺少必要字段 {field}")
39
+ return body
40
+
41
+
42
+ def is_paid(params: Mapping[str, Any]) -> bool:
43
+ """通知/查单结果是否表示支付成功。条码支付是同步返回,下单响应里用 orderState。"""
44
+ return str(params.get("state") or params.get("orderState") or "") == STATE_PAY_SUCCESS
45
+
46
+
47
+ def order_no_of(params: Mapping[str, Any]) -> Optional[str]:
48
+ """从通知里取用于幂等的单号(支付通知取 mchOrderNo,退款通知取 mchRefundNo)。"""
49
+ value = params.get("mchOrderNo") or params.get("mchRefundNo")
50
+ return None if value is None else str(value)
@@ -0,0 +1,60 @@
1
+ """签名算法。按网关公开的接口规范实现:过滤空值 -> 排序拼接 -> MD5 大写。
2
+
3
+ 这里只是按公开规范的描述(排序 + 拼接 + MD5 大写)独立实现,没有引用任何 Java 代码。
4
+ 自测向量见 ``sdk/test-vectors/sign-vectors.json``,不依赖任何 SDK 即可复核。
5
+
6
+ 注意几个容易踩的点:
7
+ 1. 空值过滤:``None`` 与 ``""`` 不参与签名,但 ``0`` / ``False`` 要参与。
8
+ 2. 排序:按整个 ``key=value&`` 片段做大小写不敏感比较。
9
+ 3. 布尔值:网关端是 ``Boolean.toString()`` -> ``true``/``false``;Python 默认是
10
+ ``True``/``False``,必须显式转换。
11
+ 4. ``bool`` 是 ``int`` 的子类,判断顺序必须先 bool 后 int。
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import hashlib
17
+ from typing import Any, Dict, Mapping, Optional
18
+
19
+
20
+ def _normalize(value: Any) -> Optional[str]:
21
+ """把参数值转成参与签名的字符串;返回 None 表示该参数不参与签名。"""
22
+ if value is None:
23
+ return None
24
+ if isinstance(value, bool):
25
+ return "true" if value else "false"
26
+ if isinstance(value, float):
27
+ # Java 端金额字段是 Long,浮点传进来必然对不上;这里直接转成整数字符串
28
+ if value.is_integer():
29
+ return str(int(value))
30
+ return repr(value)
31
+ text = str(value)
32
+ if text == "":
33
+ return None
34
+ return text
35
+
36
+
37
+ def sign_str(params: Mapping[str, Any], api_key: str) -> str:
38
+ """拼接待签名字符串(调试与分析用)。"""
39
+ items = []
40
+ for key, value in params.items():
41
+ text = _normalize(value)
42
+ if text is None:
43
+ continue
44
+ items.append(f"{key}={text}&")
45
+ items.sort(key=str.upper)
46
+ return "".join(items) + "key=" + api_key
47
+
48
+
49
+ def sign(params: Mapping[str, Any], api_key: str) -> str:
50
+ """计算签名:MD5 后转大写。"""
51
+ return hashlib.md5(sign_str(params, api_key).encode("utf-8")).hexdigest().upper()
52
+
53
+
54
+ def verify(params: Mapping[str, Any], api_key: str) -> bool:
55
+ """校验签名。``params`` 可以含 ``sign`` 字段,会自动剔除;比较不区分大小写。"""
56
+ got = str(params.get("sign") or "").strip().upper()
57
+ if not got:
58
+ return False
59
+ body: Dict[str, Any] = {k: v for k, v in params.items() if k != "sign"}
60
+ return got == sign(body, api_key)
@@ -0,0 +1,113 @@
1
+ Metadata-Version: 2.4
2
+ Name: showmac-pay
3
+ Version: 1.0.0
4
+ Summary: ShowMac 支付网关 Python 客户端(零第三方依赖)
5
+ Author: ShowMac
6
+ Keywords: showmac,payment,pay,sdk
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Operating System :: OS Independent
9
+ Requires-Python: >=3.8
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest>=7; extra == "dev"
14
+ Dynamic: license-file
15
+
16
+ # showmac-pay(Python)
17
+
18
+ ShowMac 支付网关的 Python 客户端。**零第三方依赖**,只用标准库,Python 3.8+。
19
+
20
+ ```bash
21
+ pip install ./sdk/python # 从本仓库安装(当前尚未发布到 PyPI)
22
+ ```
23
+
24
+ > 也可以只把 `sdk/python/src/showmac_pay` 整个目录拷进项目直接 import。
25
+ > 若日后发布到 PyPI,安装命令为 `pip install showmac-pay`。
26
+
27
+ ## 快速开始
28
+
29
+ ```python
30
+ import os
31
+ import time
32
+
33
+ from showmac_pay import PayError, ShowMacPay
34
+
35
+ client = ShowMacPay(
36
+ mch_no="M1621873433953",
37
+ app_id="60cc09bce4b0f1c0b83761c9",
38
+ api_key=os.environ["SHOWMAC_PAY_API_KEY"], # 应用密钥,不要硬编码
39
+ api_base="https://<支付网关域名>",
40
+ )
41
+
42
+ order = client.unified_order(
43
+ mch_order_no="mho" + str(int(time.time() * 1000)),
44
+ way_code="WX_NATIVE",
45
+ amount=100, # 单位:分,必须是整数
46
+ subject="商品标题",
47
+ body="商品描述",
48
+ notify_url="https://your-domain.com/notify/pay",
49
+ return_url="https://your-domain.com/pay/result",
50
+ channel_extra={"payDataType": "codeImgUrl"}, # 需要时传,内部会自动转 JSON
51
+ )
52
+
53
+ print(order["payOrderId"], order["payDataType"], order["payData"])
54
+ ```
55
+
56
+ 其余接口:
57
+
58
+ ```python
59
+ client.query_order(mch_order_no="mho1") # 或 pay_order_id=...
60
+ client.close_order(pay_order_id="P...")
61
+ client.refund(mch_refund_no="r1", refund_amount=100,
62
+ refund_reason="用户取消", pay_order_id="P...") # currency 默认 CNY
63
+ client.query_refund(mch_refund_no="r1")
64
+ ```
65
+
66
+ ## 异步通知
67
+
68
+ 网关用 **form 表单** POST 通知,接收方要做的三件事:验签 → 幂等 → 返回 `success`。
69
+
70
+ FastAPI 示例(Flask / Django 同理,关键是取 form 参数而不是 JSON body):
71
+
72
+ ```python
73
+ from fastapi import FastAPI, Request, Response
74
+
75
+ from showmac_pay import is_paid, order_no_of, verify_notify
76
+
77
+ app = FastAPI()
78
+
79
+
80
+ @app.post("/notify/pay")
81
+ async def notify(request: Request):
82
+ params = dict(await request.form())
83
+
84
+ try:
85
+ params = verify_notify(params, API_KEY) # 验签 + 必填字段校验
86
+ except ValueError as exc:
87
+ log.warning("通知被拒: %s", exc)
88
+ return Response("fail", media_type="text/plain")
89
+
90
+ if is_paid(params) and not already_processed(order_no_of(params)):
91
+ mark_paid(params) # 用唯一索引保证幂等
92
+
93
+ return Response("success", media_type="text/plain")
94
+ ```
95
+
96
+ `verify_notify` 除了验签,还会检查 `mchOrderNo` 非空——因为签名算法会过滤空值,
97
+ **只带 `sign` 的空报文也能算出合法签名**,只看签名等于放行空通知。
98
+
99
+ ## 行为说明
100
+
101
+ - 请求固定 `POST` + `application/json`,自动注入 `mchNo` / `appId` / `version` /
102
+ `signType` / `reqTime` / `sign`,这六个字段**不要自己再传**。
103
+ - 响应 `sign` 只覆盖 `data`(不含 `code`/`msg`),默认校验;关掉等于放弃防伪造。
104
+ - 业务失败抛 `PayError`(`.code` / `.msg` / `.raw`),响应验签失败抛 `SignatureError`。
105
+ - `amount` / `refund_amount` 会自动 `int()`:网关端是 `Long`,传浮点必然验签失败。
106
+ - 多商户:每个商户各建一个 `ShowMacPay` 实例。**不要**用全局配置(官方 Python SDK
107
+ 就是全局的,并发下会串商户)。
108
+
109
+ ## 开发
110
+
111
+ ```bash
112
+ python -m pytest # 22 个用例,含跨语言签名向量
113
+ ```
@@ -0,0 +1,14 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/showmac_pay/__init__.py
5
+ src/showmac_pay/client.py
6
+ src/showmac_pay/exceptions.py
7
+ src/showmac_pay/notify.py
8
+ src/showmac_pay/sign.py
9
+ src/showmac_pay.egg-info/PKG-INFO
10
+ src/showmac_pay.egg-info/SOURCES.txt
11
+ src/showmac_pay.egg-info/dependency_links.txt
12
+ src/showmac_pay.egg-info/requires.txt
13
+ src/showmac_pay.egg-info/top_level.txt
14
+ tests/test_showmac_pay.py
@@ -0,0 +1,3 @@
1
+
2
+ [dev]
3
+ pytest>=7
@@ -0,0 +1 @@
1
+ showmac_pay
@@ -0,0 +1,192 @@
1
+ """测试:签名向量、客户端行为、通知处理。
2
+
3
+ 运行:``python -m pytest``(只需 pytest,SDK 本身零依赖)。
4
+
5
+ 签名向量在仓库根 `sdk/test-vectors/sign-vectors.json`(各语言共用)。
6
+ 从 sdist 安装的副本里没有这个文件,向量用例会自动跳过,其余用例照常运行。
7
+ """
8
+
9
+ import json
10
+ import pathlib
11
+ import threading
12
+ from http.server import BaseHTTPRequestHandler, HTTPServer
13
+
14
+ import pytest
15
+
16
+ from showmac_pay import PayError, ShowMacPay, SignatureError, sign, sign_str, verify_notify
17
+
18
+ _VECTOR_FILE = pathlib.Path(__file__).resolve().parents[2] / "test-vectors" / "sign-vectors.json"
19
+ VECTORS = json.loads(_VECTOR_FILE.read_text(encoding="utf-8"))["vectors"] if _VECTOR_FILE.is_file() else []
20
+
21
+
22
+ # ---------------------------------------------------------------- 签名向量
23
+ # 向量为空时 parametrize 会把这组用例标为 skip,不影响其余用例
24
+
25
+ @pytest.mark.parametrize("vector", VECTORS, ids=[v["name"] for v in VECTORS])
26
+ def test_sign_matches_vector(vector):
27
+ assert sign(vector["params"], vector["apiKey"]) == vector["expected"]
28
+
29
+
30
+ @pytest.mark.parametrize("vector", VECTORS, ids=[v["name"] for v in VECTORS])
31
+ def test_sign_str_matches_canonical(vector):
32
+ """规范化字符串本身也要对:签名对、串不对,说明是碰巧撞上的。"""
33
+ assert sign_str(vector["params"], vector["apiKey"]) == vector["canonical"] + "key=" + vector["apiKey"]
34
+
35
+
36
+ def test_empty_values_filtered():
37
+ assert sign_str({"a": "1", "b": "", "c": None}, "K") == "a=1&key=K"
38
+
39
+
40
+ def test_zero_is_not_empty():
41
+ assert "amount=0&" in sign_str({"amount": 0}, "K")
42
+
43
+
44
+ def test_bool_uses_java_lowercase():
45
+ assert sign_str({"paid": True}, "K") == "paid=true&key=K"
46
+ assert sign_str({"paid": False}, "K") == "paid=false&key=K"
47
+
48
+
49
+ def test_float_amount_normalized_to_int():
50
+ assert sign_str({"amount": 1.0}, "K") == sign_str({"amount": 1}, "K")
51
+
52
+
53
+ def test_sort_is_case_insensitive():
54
+ assert sign_str({"b": "1", "A": "2"}, "K") == sign_str({"A": "2", "b": "1"}, "K")
55
+
56
+
57
+ def test_verify_ignores_sign_field_and_case():
58
+ from showmac_pay import verify
59
+
60
+ params = {"a": "1", "b": "2"}
61
+ params["sign"] = sign(params, "K").lower()
62
+ assert verify(params, "K")
63
+
64
+
65
+ # ---------------------------------------------------------------- 通知
66
+
67
+ def test_verify_notify_ok():
68
+ params = {"mchOrderNo": "mho1", "state": "2", "amount": "1"}
69
+ params["sign"] = sign(params, "K")
70
+ assert verify_notify(params, "K")["mchOrderNo"] == "mho1"
71
+
72
+
73
+ def test_verify_notify_rejects_tampered():
74
+ params = {"mchOrderNo": "mho1", "amount": "1"}
75
+ params["sign"] = sign(params, "K")
76
+ with pytest.raises(ValueError, match="验签失败"):
77
+ verify_notify({**params, "amount": "100"}, "K")
78
+
79
+
80
+ def test_verify_notify_rejects_sign_only_payload():
81
+ """只带 sign 的空报文也能算出合法签名,必须靠必填字段拦住。"""
82
+ with pytest.raises(ValueError, match="mchOrderNo"):
83
+ verify_notify({"sign": sign({}, "K")}, "K")
84
+
85
+
86
+ def test_verify_notify_rejects_missing_sign():
87
+ with pytest.raises(ValueError, match="缺少 sign"):
88
+ verify_notify({"mchOrderNo": "mho1"}, "K")
89
+
90
+
91
+ # ---------------------------------------------------------------- 客户端
92
+
93
+ class _Handler(BaseHTTPRequestHandler):
94
+ """假网关:记录收到的请求,按预设返回响应。"""
95
+
96
+ response: dict = {}
97
+ received: dict = {}
98
+
99
+ def do_POST(self): # noqa: N802
100
+ length = int(self.headers.get("Content-Length", 0))
101
+ body = json.loads(self.rfile.read(length))
102
+ type(self).received = {"path": self.path, "body": body,
103
+ "content_type": self.headers.get("Content-Type")}
104
+ payload = json.dumps(type(self).response, ensure_ascii=False).encode()
105
+ self.send_response(200)
106
+ self.send_header("Content-Type", "application/json; charset=UTF-8")
107
+ self.send_header("Content-Length", str(len(payload)))
108
+ self.end_headers()
109
+ self.wfile.write(payload)
110
+
111
+ def log_message(self, *args): # 静默
112
+ pass
113
+
114
+
115
+ @pytest.fixture()
116
+ def gateway():
117
+ server = HTTPServer(("127.0.0.1", 0), _Handler)
118
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
119
+ thread.start()
120
+ yield f"http://127.0.0.1:{server.server_address[1]}", _Handler
121
+ server.shutdown()
122
+
123
+
124
+ def make_client(base, api_key="K"):
125
+ return ShowMacPay("M1", "A1", api_key, base)
126
+
127
+
128
+ def ok_response(data: dict, api_key="K"):
129
+ return {"code": 0, "msg": "SUCCESS", "data": data, "sign": sign(data, api_key)}
130
+
131
+
132
+ def test_unified_order_injects_public_fields(gateway):
133
+ base, handler = gateway
134
+ data = {"payOrderId": "P1", "orderState": 1, "payDataType": "codeUrl",
135
+ "payData": "weixin://x"}
136
+ handler.response = ok_response(data)
137
+
138
+ res = make_client(base).unified_order(
139
+ mch_order_no="mho1", way_code="WX_NATIVE", amount=1,
140
+ subject="标题", body="描述", channel_extra={"payDataType": "codeImgUrl"})
141
+
142
+ body = handler.received["body"]
143
+ assert handler.received["path"] == "/api/pay/unifiedOrder"
144
+ assert body["mchNo"] == "M1" and body["appId"] == "A1"
145
+ assert body["version"] == "1.0" and body["signType"] == "MD5"
146
+ assert body["reqTime"].isdigit() and len(body["reqTime"]) == 13
147
+ assert body["channelExtra"] == '{"payDataType":"codeImgUrl"}'
148
+ assert body["sign"] == sign({k: v for k, v in body.items() if k != "sign"}, "K")
149
+ assert res["payOrderId"] == "P1"
150
+
151
+
152
+ def test_business_error_raises(gateway):
153
+ base, handler = gateway
154
+ handler.response = {"code": 9999, "msg": "验签失败"}
155
+ with pytest.raises(PayError) as exc:
156
+ make_client(base).query_order(mch_order_no="mho1")
157
+ assert exc.value.code == 9999 and "验签失败" in exc.value.msg
158
+
159
+
160
+ def test_tampered_response_rejected(gateway):
161
+ base, handler = gateway
162
+ handler.response = ok_response({"payOrderId": "P1"})
163
+ handler.response["data"]["payOrderId"] = "P2" # 篡改但沿用旧签名
164
+ with pytest.raises(SignatureError, match="响应验签失败"):
165
+ make_client(base).query_order(mch_order_no="mho1")
166
+
167
+
168
+ def test_verify_response_can_be_disabled(gateway):
169
+ base, handler = gateway
170
+ handler.response = ok_response({"payOrderId": "P1"})
171
+ handler.response["data"]["payOrderId"] = "P2"
172
+ client = ShowMacPay("M1", "A1", "K", base, verify_response=False)
173
+ assert client.query_order(mch_order_no="mho1")["payOrderId"] == "P2"
174
+
175
+
176
+ def test_query_requires_one_order_no():
177
+ with pytest.raises(ValueError, match="至少传一个"):
178
+ make_client("http://127.0.0.1:1").query_order()
179
+
180
+
181
+ def test_refund_sends_required_fields(gateway):
182
+ base, handler = gateway
183
+ handler.response = ok_response({"refundOrderId": "R1", "state": 1})
184
+ make_client(base).refund(mch_refund_no="r1", refund_amount=1,
185
+ refund_reason="用户取消", pay_order_id="P1")
186
+ body = handler.received["body"]
187
+ assert body["currency"] == "CNY" and body["refundReason"] == "用户取消"
188
+
189
+
190
+ def test_network_error_raises_pay_error():
191
+ with pytest.raises(PayError, match="网络异常"):
192
+ make_client("http://127.0.0.1:1", ).query_order(mch_order_no="x")