💳 支付接入材料清单
电商平台从「演示支付」切换到「真实收款」前，需要准备的主体资质、渠道材料、技术配置与合规事项。适用于本站 server/shop/payment.js 的统一支付适配层。
微信支付 Native / JSAPI支付宝电脑网站支付银联云闪付 / 聚合收单短信验证码AI 客服合规
⚠️ 当前状态：本站默认运行在 演示支付（沙箱）模式（SHOP_PAY_SANDBOX=1），所有渠道只做订单状态流转，不跳转真实收银台、不产生资金往来。真实收款必须先完成下列材料准备、拿到商户凭证、通过渠道沙箱联调，并把该变量设为 0。
0通用资质（所有渠道都要）
这部分是「主体资格」，任何一家支付机构/收单机构入网都会核验，建议先一次备齐扫描件并加盖公章。
主体与结算
- 营业执照：企业或个体工商户，经营范围需覆盖所售商品类目；食品、图书、医疗器械、教育培训等另需对应经营许可证
- 法人身份证正反面彩色扫描件；经办人办理时还需经办人身份证 + 加盖公章的授权书
- 对公银行结算账户：开户许可证或银行开户回执（个体工商户部分渠道可用法人个人账户）
- 结算周期、手续费率、发票开具信息与开票主体确认
网站与合规
- 已完成 ICP 备案的域名（本站：浙ICP备2026097921号）+ 有效 SSL 证书，全站 HTTPS
- 可公开访问且内容完整的：用户协议、隐私政策、退换货/售后规则、客服电话、商品价格与发票说明
- 经营场景材料：网站首页/商品页/结算页截图、门头或办公场所照片（部分渠道要求）
- 合规义务：《个人信息保护法》告知同意、明码标价、7 天无理由退货、订单与支付日志留存、投诉与人工客服入口
主体一致性是最常见的驳回原因：营业执照主体 = 支付商户号主体 = ICP 备案主体 = 银行开户主体，四者不一致需提供授权/关系证明或先做变更。
1微信支付（Native 扫码 / 公众号 JSAPI）
对应渠道 ID wechat_native / wechat_jsapi，协议为微信支付 APIv3。
需要准备的材料
- 营业执照、法人身份证正反面、经办人证件与授权书、对公账户证明（见第 0 节）
- 已微信认证的服务号 / 小程序 / 开放平台应用及其 AppID（微信认证按年审核并缴费）
- 微信支付商户号 mchid：在微信支付商户平台提交资料申请，并完成 AppID 与商户号的绑定
- APIv3 密钥（32 位随机字符串，需自行生成并妥善保存）
- 商户 API 证书：apiclient_key.pem（商户私钥，仅服务端保存）与 证书序列号 serial_no
- 微信支付平台证书 / 公钥：用于回调验签（也可通过接口下载并定期轮换）
- 已 ICP 备案、HTTPS 的 支付回调域名；Native 还需配置支付授权目录/场景
- JSAPI 额外材料：服务号 AppSecret、网页授权域名（公众号后台配置）、后端以 code 换取 openid 的能力
接入步骤
- 注册并认证服务号/小程序 → 拿到 AppID
- 商户平台提交营业执照等资料 → 申请商户号 mchid → 签署线上协议
- 配置 APIv3 密钥、下载商户 API 证书、登记证书序列号
- 绑定 AppID，配置支付授权目录与回调域名
- 沙箱/小额真实交易联调：下单 → 支付 → 回调验签 → 查询 → 退款 → 对账，通过后再放量
本站已实现 v3 的 RSA-SHA256 请求签名、Native/JSAPI 下单与回调验签 + AES-GCM 解密骨架，但未经过真实商户沙箱联调。上线前必须用真实凭证在渠道沙箱完整跑通，尤其验证回调验签与金额校验。
2支付宝（电脑网站支付）
对应渠道 ID alipay_page，协议为开放平台 alipay.trade.page.pay + RSA2 签名。
需要准备的材料
- 企业支付宝账号并完成实名认证（个体工商户可用对应主体账户）
- 支付宝开放平台应用 AppID，并签约「电脑网站支付」产品
- 签约材料：网站首页 / 商品详情页 / 支付页 URL、ICP 备案截图、经营类目与商品说明、营业执照与法人证件
- RSA2 密钥对：应用私钥（本地保存，绝不入前端/仓库）+ 应用公钥（上传平台后换取支付宝公钥）
- 外网可访问的 HTTPS 异步通知 notify_url 与 同步跳转 return_url
- 应用网关 / 授权回调地址（按开放平台应用配置要求）
接入步骤
- 创建开放平台应用，用工具生成 RSA2 密钥对
- 上传应用公钥、保存支付宝公钥
- 提交网站信息签约电脑网站支付，等待审核
- 配置 notify_url / return_url，使用沙箱环境联调
- 校验回调 sign、app_id、total_amount、trade_status 与商户订单号后再入账
3银联云闪付 / 聚合收单
对应渠道 ID unionpay。通常经银行、持牌支付机构或聚合服务商入网，具体字段以服务商文档为准。
需要准备的材料
- 营业执照、法人身份证、开户许可证 / 对公账户证明
- 经营场所照片：门头、店内、收银台；经营类目与 MCC 商户类别码
- 收单机构入网申请表与协议、结算账户信息
- 测试商户号与生产商户号 merId，交易私钥/证书、银联或机构公钥（验签用）
- HTTPS 前台通知 / 后台通知地址、对账文件下载权限
- 入网测试报告：消费、撤销、退货、退款、对账等场景
聚合支付服务商（如收钱吧、拉卡拉等）会代接入多家渠道，材料略少，但要额外确认资金清算主体、二清风险、费率与到账周期。本站实现的是「可配置网关转发」适配器，联调时需按机构文档调整签名串与字段名。
4站内方式（无需外部支付资质）
- 账户余额 balance：站内账务，无需支付牌照材料，但需明确「演示余额不可提现、无现金价值」；若改为可充值预付余额，则涉及单用途预付卡/资金池合规，需另行评估。
- 货到付款 cod：无需支付接口，但要有签收验收、拒收与退换货条款，并在后台记录收款状态（本站已提供「标记已收款」）。
5手机验证码注册 / 登录
本功能依赖短信服务，与支付分开申请，但同样是上线前必备。
- 阿里云 / 腾讯云等短信服务企业实名认证账号
- 短信签名：需提交营业执照、备案域名或应用名称审核，签名需与主体/网站相关
- 验证码短信模板及审核通过的 模板 CODE（内容含有效期与用途说明）
- AccessKey ID / Secret（建议最小权限子账号），以及日发送额度与告警
- 防刷策略：60 秒发送间隔、单号码每日上限、图形/行为验证、异常号码拦截、发送日志留存
本站复用家政 SaaS 已有的短信网关契约：配置 SMS_API_URL + SMS_API_KEY 后自动切换为真实发送；未配置时为演示模式，验证码在页面上回显。上线务必关闭演示模式并开启频控（服务端已内置 60 秒 / 每日 10 次 / 5 分钟过期 / 错误 5 次锁定）。
6AI 客服合规与技术准备
- 大模型服务 API Key：本站复用 OPENAI_API_KEY / OPENAI_BASE 兼容接口，可用百炼、混元、DeepSeek 等
- 客服知识库：商品信息、运费规则、发货时效、退换货政策、发票规则、客服电话与工作时间
- 按实际服务形态确认生成式 AI 服务备案 / 内容安全审核要求，保留会话日志、敏感信息脱敏
- 人工接管与投诉入口：本站对投诉、退款纠纷、低置信度问题自动转人工，后台可切换 AI / 人工 / 关闭会话
- 明确告知用户正在与 AI 对话；AI 不得编造物流单号、金额、赔付承诺，不得索要验证码、银行卡号等敏感信息
7技术准备（开发侧检查项）
安全
- 回调 notify_url 必须外网可达、HTTPS、验签并幂等处理，重复通知不得重复入账
- 商户私钥/证书只放服务端文件并设置最小权限，绝不入前端、绝不提交 Git
- 订单金额一律由服务端按商品 ID 重算，禁止信任前端价格
- 回调需校验商户号、订单号、金额、交易状态与渠道，防止伪造与金额篡改
交易一致性
- 下单预扣库存 + 支付超时回滚（本站 30 分钟），避免超卖
- 支付单与订单分离、状态机单向流转；主动查询补偿回调丢失
- 退款、撤销、部分退款与对账文件核对流程
- 沙箱 / 生产两套配置隔离，密钥轮换与证书到期提醒
本站回调地址（部署后需在各渠道后台配置）
| 渠道 | 回调 URL |
|---|
| 微信支付 Native | https://beiwh.top/api/shop/pay/notify/wechat_native |
| 微信支付 JSAPI | https://beiwh.top/api/shop/pay/notify/wechat_jsapi |
| 支付宝电脑网站 | https://beiwh.top/api/shop/pay/notify/alipay_page |
| 银联 / 聚合收单 | https://beiwh.top/api/shop/pay/notify/unionpay |
8环境变量对照表
在服务器 server/.env 中配置；.env 已被 Git 忽略，不会入库。
| 变量 | 用途 | 对应渠道 |
|---|
| SHOP_PAY_SANDBOX | 设为 0 才允许真实下单（默认 1 演示） | 全部 |
| WXPAY_MCHID / WXPAY_APPID | 商户号 / 应用 AppID | 微信支付 |
| WXPAY_SERIAL_NO / WXPAY_APIV3_KEY | 证书序列号 / APIv3 密钥 | 微信支付 |
| WXPAY_PRIVATE_KEY_PATH / WXPAY_PLATFORM_KEY_PATH | 商户私钥 / 平台公钥文件路径 | 微信支付 |
| ALIPAY_APPID | 开放平台应用 ID | 支付宝 |
| ALIPAY_PRIVATE_KEY_PATH / ALIPAY_PUBLIC_KEY_PATH | 应用私钥 / 支付宝公钥 | 支付宝 |
| UNIONPAY_MER_ID / UNIONPAY_GATEWAY_URL / UNIONPAY_CERT_PATH | 商户号 / 网关 / 交易证书 | 银联 / 聚合 |
| SMS_API_URL / SMS_API_KEY | 短信网关与鉴权（不配则演示模式） | 注册登录 |
| OPENAI_API_KEY / OPENAI_BASE / SHOP_AI_MODEL | AI 客服大模型（不配则本地知识库） | AI 客服 |
| SHOP_JWT_SECRET / SHOP_ADMIN_PASSWORD | 登录令牌签名密钥 / 后台初始密码，生产必改 | 全站 |
| SHOP_BASE_URL | 回调域名前缀，默认 https://beiwh.top | 全部 |
9上线前逐项检查
- 营业执照、法人证件、对公账户、ICP 备案与 HTTPS 全部有效且主体一致
- 用户协议、隐私政策、退换货规则、客服电话、价格与发票说明页面可公开访问
- 已取得至少一个渠道的商户号，并完成 AppID 绑定 / 产品签约
- 商户私钥与平台公钥已按最小权限挂载到服务端，确认 未进入 Git 仓库
- 短信签名与模板审核通过，演示验证码回显已关闭
- 沙箱完成：下单 → 支付 → 回调验签 → 主动查询 → 退款 → 对账 全链路演练
- 回调幂等、金额服务端重算、库存预扣与超时回滚均已验证
- AI 客服知识库已按真实店铺政策更新，转人工与投诉通道可用
- SHOP_JWT_SECRET、SHOP_ADMIN_PASSWORD、POSTGRES_PASSWORD 已改为强随机值
- 数据库不对公网开放；日志、对账、告警与备份机制就绪
- 把 SHOP_PAY_SANDBOX 设为 0，重启服务并用小额真实订单验证
费率、审核周期、认证费用与所需材料会随平台政策调整，请以微信支付商户平台、支付宝开放平台及收单机构的最新官方文档为准。本清单是工程准备指引，不构成法律或合规意见。