系统概览
本站是一套零运行时依赖的 Node.js 应用:静态页面由构建脚本生成,服务端只使用 Node 内置模块(node:http、node:crypto、fetch)完成支付签名、回调验签、订单存储与后台管理。没有第三方支付 SDK,签名逻辑全部可审计。
| 模块 | 职责 | 关键文件 |
|---|---|---|
| 站点 | 官网、业务范围、收银台、订单、法务页 | site/ · public/ |
| 微信支付 | APIv3 签名、下单、查单、退款、回调解密 | server/wechat.js |
| 支付宝 | RSA2 签名、页面支付、查单、退款、验签 | server/alipay.js |
| 订单编排 | 服务端定价、统一订单、演示支付、退款 | server/payments.js |
| 安全 | CSRF、Origin、限流、密码哈希、响应头 | server/http.js · server/password.js |
| 存储 | 订单、退款、留言的原子写入 | data/db.json |
金额单位在内部一律使用整数分(500000 表示 ¥5,000.00),调用支付宝时再转换为两位小数的元字符串,避免浮点误差。前端不能提交金额,服务端只接受服务项目 ID 并从价目表取价。
快速开始
需要 Node.js 20.11 及以上版本。项目不依赖 npm 包,构建脚本使用仓库内的二维码生成器。
# 1. 生成静态页面
npm run build
# 2. 配置
cp .env.example .env
npm run admin:hash -- "至少10位的强密码"
# 把输出的 ADMIN_PASSWORD_HASH 写入 .env
# 生成 SESSION_SECRET:
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
# 3. 启动
npm start
# → http://127.0.0.1:3080未填写商户密钥时,非生产环境可进入演示模式:完整走通下单、订单状态、退款与对账,但不发生真实资金流转。演示模式在生产环境强制关闭,未配置的渠道会显示为「暂未开通」。
接口与 CSRF
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/csrf | 下发 CSRF Cookie,并返回 token |
| GET | /api/site | 服务项目、金额、支付渠道可用状态 |
| POST | /api/orders | 创建订单并返回二维码 / 跳转地址(需 CSRF) |
| GET | /api/orders/{id}?sync=1 | 查询订单,可选向渠道主动查单 |
| POST | /api/orders/{id}/close | 关闭未支付订单(需 CSRF) |
| POST | /api/notify/wechat | 微信支付异步通知(验签 + 解密) |
| POST | /api/notify/alipay | 支付宝异步通知(RSA2 验签) |
| POST | /api/contact | 需求登记(需 CSRF) |
| POST | /api/admin/login | 后台登录(需 CSRF,限流) |
| GET | /api/admin/orders | 订单列表(需管理员会话) |
| POST | /api/admin/orders/{id}/refund | 退款(需管理员会话 + CSRF) |
创建订单
// 先 GET /api/csrf,带上 yk_csrf Cookie 与 X-CSRF-Token 头
{
"productId": "software", // 服务项目 ID,金额由服务端价目表决定
"channel": "wechat" // wechat | alipay
}{
"order": {
"id": "YK20261118210605A1B2C3D4E5F6",
"outTradeNo": "YK20261118210605C3D4E5F6G7H8",
"amount": 500000,
"status": "pending",
"mode": "live",
"expiresAt": "2026-11-18T13:36:05.000Z"
},
"payload": {
"type": "qr",
"codeUrl": "weixin://wxpay/bizpayurl?pr=xxxx"
}
}payload.type 为 qr 时渲染二维码;为 redirect 时跳转 payload.url。电脑端微信走 Native,手机微信走 H5;电脑支付宝走电脑网站支付,手机支付宝走手机网站支付,由服务端根据 User-Agent 选择。
微信支付(APIv3)
请求使用商户 API 私钥签名:方法\nURL\n时间戳\n随机串\n请求体\n,URL 必须包含查询参数。响应与回调使用平台证书或微信支付公钥验签;回调 resource 使用 32 位 APIv3 密钥做 AES-256-GCM 解密。
WECHATPAY2-SHA256-RSA2048 mchid="1900000001",
nonce_str="...", signature="...",
timestamp="1731900000", serial_no="40位证书序列号"| 产品 | 接口 | 返回 |
|---|---|---|
| Native 扫码 | POST /v3/pay/transactions/native | code_url |
| H5 支付 | POST /v3/pay/transactions/h5 | h5_url |
| 查单 | GET /v3/pay/transactions/out-trade-no/{no} | trade_state |
| 关单 | POST .../out-trade-no/{no}/close | 204 |
| 退款 | POST /v3/refund/domestic/refunds | refund_id / status |
| 对账单 | GET /v3/bill/tradebill | download_url |
回调校验
除了验签与 5 分钟时间戳窗口,本系统还会校验回调中的 mchid、appid、订单渠道、金额与币种。任何一项不一致都会记录异常并返回失败,避免其他商户或测试环境的通知串入。
const ok = crypto.createVerify('RSA-SHA256')
.update(`${timestamp}\n${nonce}\n${rawBody}\n`)
.verify(verifier, signature, 'base64');
const decipher = crypto.createDecipheriv(
'aes-256-gcm', Buffer.from(apiV3Key), Buffer.from(resource.nonce)
);
decipher.setAuthTag(ciphertext.subarray(-16));
decipher.setAAD(Buffer.from(resource.associated_data));处理成功后返回 HTTP 200 与 {"code":"SUCCESS","message":"成功"};返回非 200 微信会重试,因此业务处理必须幂等。
支付宝(RSA2)
公共参数包含 app_id、method、charset、sign_type=RSA2、timestamp、version=1.0、biz_content。签名串为按键名升序、过滤空值与 sign 后的 k=v&...,用应用私钥 SHA256withRSA 签名。
| 产品 | 接口 | 说明 |
|---|---|---|
| 电脑网站支付 | alipay.trade.page.pay | 跳转支付宝收银台,FAST_INSTANT_TRADE_PAY |
| 手机网站支付 | alipay.trade.wap.pay | QUICK_WAP_WAY |
| 当面付 · 扫码 | alipay.trade.precreate | 返回 qr_code,可选 |
| 查单 / 关单 | alipay.trade.query / close | 订单状态维护 |
| 退款 | alipay.trade.refund | 支持全额 / 部分退款 |
| 对账单 | alipay.data.dataservice.bill.downloadurl.query | 按日下载 |
异步通知验签
支付宝以 application/x-www-form-urlencoded POST 通知,参数已 URL 解码。验签时排除 sign 与 sign_type,其余参数按键名排序拼接,用支付宝公钥验证。验签通过后还要校验 app_id、seller_id、charset、金额与订单渠道。
const content = Object.keys(params)
.filter((k) => k !== 'sign' && k !== 'sign_type' && params[k] !== '')
.sort()
.map((k) => `${k}=${params[k]}`)
.join('&');
const valid = crypto.createVerify('RSA-SHA256')
.update(content)
.verify(alipayPublicKey, params.sign, 'base64');处理成功必须输出纯文本 success,否则支付宝会在 25 小时内多次重试。
回调与幂等
- 以商户单号 out_trade_no 作为唯一业务键,重复回调只入账一次。
- 回调金额、币种、商户号、appid / seller_id 与订单渠道逐项校验,不一致拒绝入账。
- 微信时间戳必须在 5 分钟内;订单号与退款单号均使用加密随机串,降低枚举风险。
- 所有状态变更写入 events 时间线,后台可查看完整处理记录。
- 后台登录使用 scrypt 密码哈希、HttpOnly Cookie、CSRF Token 与登录限流。
退款与对账
后台支持全额与部分退款:累计退款金额不得超过订单金额,退款单号独立生成。微信退款结果由异步通知回写;支付宝退款以同步响应为准,可在后台查看状态。
| 能力 | 微信支付 | 支付宝 |
|---|---|---|
| 申请退款 | POST /v3/refund/domestic/refunds | alipay.trade.refund |
| 退款查询 | GET /v3/refund/domestic/refunds/{no} | alipay.trade.fastpay.refund.query |
| 交易对账单 | GET /v3/bill/tradebill | alipay.data.dataservice.bill.downloadurl.query |
| 主动查单 | GET /v3/pay/transactions/out-trade-no/{no} | alipay.trade.query |
| 关闭订单 | POST .../close | alipay.trade.close |
商户开通清单
代码已经把接口写好,但商户号与收款产品必须由支付机构审核开通。以下清单按当前实际要求整理,审核时效以平台为准。
共同资料
- 营业执照(个体工商户)彩色照片或扫描件,四角完整、字迹清晰。
- 经营者身份证正反面,与执照登记的经营者一致。
- 结算账户:对公账户,或经营者本人银行卡(以平台页面要求为准)。
- 经营场所证明:门头照 / 店内照,或线上经营链接(网站需 ICP 备案)。
- 客服联系方式、商户简称、经营类目。
- 已完成 ICP 备案的域名(本站在 pay.paysphere.cn,备案号 滇ICP备2026021450号),备案主体与营业执照一致,站点内容与经营范围相符。
微信支付
- 在微信支付商户平台提交资料,完成账户验证。
- 产品中心开通 Native 支付、H5 支付;需要公众号 / 小程序 / APP 时再开通对应产品。
- H5 支付要求网站已备案、经营内容合规,需填写场景说明与域名。
- 账户中心 → API 安全:申请商户 API 证书、设置 32 位 APIv3 密钥、记录证书序列号。
- 把 apiclient_key.pem 放入 secrets/,填写 WECHAT_MCHID / WECHAT_APPID / WECHAT_SERIAL_NO / WECHAT_API_V3_KEY。
- 配置回调:/api/notify/wechat 与 /api/notify/wechat-refund,必须 HTTPS。
支付宝
- 注册支付宝商家账号,完成实名认证与经营者核验。
- 创建网页应用,签约「电脑网站支付」「手机网站支付」;需要当面付时单独签约。
- 上传应用公钥,获取支付宝公钥;私钥使用 PKCS#8 格式。
- 填写 ALIPAY_APP_ID / ALIPAY_SELLER_ID / ALIPAY_PRIVATE_KEY_PATH / ALIPAY_PUBLIC_KEY_PATH。
- 配置异步通知 /api/notify/alipay 与同步跳转 /api/alipay/return。
费率与结算
| 项目 | 微信支付 | 支付宝 |
|---|---|---|
| 标准费率 | 0.6%(部分类目 0.38%) | 0.6%(部分类目 0.38%) |
| 结算周期 | T+1 | T+1 |
| 结算账户 | 对公账户 / 经营者个人账户 | 对公账户 / 经营者个人账户 |
| 退款手续费 | 按签约规则,通常退还 | 按签约规则 |
费率与结算规则由支付机构根据经营类目核定,最终以商户平台签约页为准。跨境、分账、周期扣款、花呗分期等产品需额外资质与单独签约。
错误码
| code | 含义 | 处理建议 |
|---|---|---|
| PRODUCT_INVALID | 服务项目 ID 无效 | 从 /api/site 的 products 中取值 |
| CHANNEL_UNAVAILABLE | 渠道未配置或未开通 | 补齐 .env 并重启,或选择另一渠道 |
| CSRF_INVALID | CSRF 校验失败 | 先 GET /api/csrf,带 Cookie 与 X-CSRF-Token |
| SIGN_INVALID | 应答或回调验签失败 | 核对公钥 / 平台证书与密钥版本 |
| REFUND_AMOUNT_INVALID | 退款金额超过可退余额 | 按订单详情中的可退金额重试 |
| RATE_LIMITED | 请求过于频繁 | 按 Retry-After 退避 |
| UNAUTHORIZED | 后台会话失效 | 重新登录 |
部署上线
生产环境建议:Ubuntu / Debian + Node.js 22 LTS + Nginx + HTTPS。Node 服务只监听 127.0.0.1,由 Nginx 终止 TLS 并反代。仓库 deploy/ 目录有可直接修改的配置。
server {
listen 80;
server_name pay.paysphere.cn;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name pay.paysphere.cn;
ssl_certificate /etc/letsencrypt/live/pay.paysphere.cn/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/pay.paysphere.cn/privkey.pem;
client_max_body_size 1m;
location / {
proxy_pass http://127.0.0.1:3080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}[Unit]
Description=Yongkun Studio Website & Payment
After=network.target
[Service]
Type=simple
WorkingDirectory=/srv/yongkun-studio
ExecStart=/usr/bin/node server/index.js
Restart=always
Environment=NODE_ENV=production
User=www-data
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/srv/yongkun-studio/data
[Install]
WantedBy=multi-user.target- 先设置 ADMIN_PASSWORD_HASH 与 SESSION_SECRET,再执行 npm run build,最后重启服务。
- data/ 目录纳入每日备份;secrets/ 权限设为 600,且不要提交到 Git。
- 确认域名 ICP 备案通过(滇ICP备2026021450号),页脚已展示备案号并链接工信部查询页。
- 在微信支付 / 支付宝后台把回调地址改为 https://pay.paysphere.cn/...。
- 上线后用 ¥0.01 真实订单走一遍:下单 → 支付 → 回调 → 退款 → 对账。