服务 方案 流程 报价 业务范围 关于 项目咨询 在线支付
技术文档 / DOCUMENTATION

支付接入与部署

微信支付 APIv3 与支付宝开放平台的签名、回调验签、退款与对账。示例代码与本系统运行逻辑一致,可用于联调与二次开发。

系统概览

本站是一套零运行时依赖的 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 包,构建脚本使用仓库内的二维码生成器。

bash
# 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

未填写商户密钥时,非生产环境可进入演示模式:完整走通下单、订单状态、退款与对账,但不发生真实资金流转。演示模式在生产环境强制关闭,未配置的渠道会显示为「暂未开通」。

生产启动硬校验:必须使用 HTTPS 的 SITE_URL、ADMIN_PASSWORD_HASH 与至少 32 字符的 SESSION_SECRET;PAY_MODE=mock 会被拒绝。配置不完整时进程直接退出,避免带着默认密码上线。

接口与 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)

创建订单

POST /api/orders
// 先 GET /api/csrf,带上 yk_csrf Cookie 与 X-CSRF-Token 头
{
  "productId": "software",       // 服务项目 ID,金额由服务端价目表决定
  "channel": "wechat"           // wechat | alipay
}
201 Created
{
  "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 解密。

Authorization
WECHATPAY2-SHA256-RSA2048 mchid="1900000001",
  nonce_str="...", signature="...",
  timestamp="1731900000", serial_no="40位证书序列号"
产品接口返回
Native 扫码POST /v3/pay/transactions/nativecode_url
H5 支付POST /v3/pay/transactions/h5h5_url
查单GET /v3/pay/transactions/out-trade-no/{no}trade_state
关单POST .../out-trade-no/{no}/close204
退款POST /v3/refund/domestic/refundsrefund_id / status
对账单GET /v3/bill/tradebilldownload_url

回调校验

除了验签与 5 分钟时间戳窗口,本系统还会校验回调中的 mchid、appid、订单渠道、金额与币种。任何一项不一致都会记录异常并返回失败,避免其他商户或测试环境的通知串入。

server/wechat.js
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.payQUICK_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、金额与订单渠道。

server/alipay.js
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/refundsalipay.trade.refund
退款查询GET /v3/refund/domestic/refunds/{no}alipay.trade.fastpay.refund.query
交易对账单GET /v3/bill/tradebillalipay.data.dataservice.bill.downloadurl.query
主动查单GET /v3/pay/transactions/out-trade-no/{no}alipay.trade.query
关闭订单POST .../closealipay.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+1T+1
结算账户对公账户 / 经营者个人账户对公账户 / 经营者个人账户
退款手续费按签约规则,通常退还按签约规则

费率与结算规则由支付机构根据经营类目核定,最终以商户平台签约页为准。跨境、分账、周期扣款、花呗分期等产品需额外资质与单独签约。

错误码

code含义处理建议
PRODUCT_INVALID服务项目 ID 无效从 /api/site 的 products 中取值
CHANNEL_UNAVAILABLE渠道未配置或未开通补齐 .env 并重启,或选择另一渠道
CSRF_INVALIDCSRF 校验失败先 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/ 目录有可直接修改的配置。

/etc/nginx/sites-available/paysphere.conf
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;
  }
}
/etc/systemd/system/yongkun.service
[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 真实订单走一遍:下单 → 支付 → 回调 → 退款 → 对账。
需要协助?添加微信 ,备注「支付接入」。