俱乐部 H5 · 微信收款
支付链路接入教程
🔒 安全承诺
请放心填写。API 无出只进，数据全程加密存储；即使被获取，也只能用于你自己的服务号收款，不会有资金损失。
00先搞懂你要做什么
- 平台不碰你的钱。平台只提供程序、服务器和指导；你用自己的「已认证服务号 + 微信商户号」收款，资金直达你自己的微信支付账户（平台不经手，规避二清合规问题）。
- 你只做两件事：① 在微信侧开通支付、拿到一串"钥匙"；② 把这串钥匙填进我们的商户后台。
- 域名由平台超管绑定。你不用管域名；我们同步域名解析和账号数据后，你的 H5 即可访问（还不可下单），你先配好前台内容，再等技术人员做支付测试，通过后正式上线。
01开始前的准备条件
| # | 条件 | 说明 |
|---|---|---|
| 1 | 营业执照 | 公司 / 个体工商户均可注册微信支付。主体是公司可额外开通 H5 支付（微信外浏览器也能付） |
| 2 | 已认证服务号 | ⚠️ 必须是服务号。订阅号没有网页授权能力，无法做 H5 微信支付 |
| 3 | 结算银行账户 | 微信支付结算资金到账用 |
| 4 | 你的域名（告知我们即可） | 由平台超管后台绑定，商户后台无此入口 |
02第一步：注册微信支付商户号
入口https://pay.weixin.qq.com/ → 首页「成为商家」→ 注册微信支付商户号
- 用微信扫码 / 邮箱注册，选择主体类型（企业 / 个体工商户）。
- 提交营业执照、法人身份信息、结算银行账户、超级管理员信息。
- 等待审核（一般 1–5 个工作日），通过后登录商户平台。
完成后你能看到
- 登录账号：你登录商户平台用的账号（邮箱/微信号）。
- 商户号（mch_id）：一串数字（通常以
1开头），在「账户中心 → 商户信息」查看。
别搞混
「登录账号」是给你登录用的；商户号是那串数字，一会儿要填进我们后台。
03第二步：开通支付产品
入口商户平台 → 产品中心 → 支付产品
| 产品 | 是否必开 | 用途 |
|---|---|---|
| JSAPI 支付 | 必开 | H5 内微信支付（用户点一下即付） |
| Native 支付 | 建议开 | 扫码支付，兜底通道 |
| H5 支付 | 公司主体可开 | 微信客户端外的移动浏览器也能付款 |
04第三步：配置 API 安全（拿"钥匙"）
入口商户平台 → 账户中心 → API 安全
| 项目 | 操作 | 得到什么 / 用途 |
|---|---|---|
| 商户 APIv2 密钥 | 「修改」→ 设置 32 位密钥 | 当前下单与回调验签就用它（最重要的一把钥匙） |
| 商户 API 证书 | 「管理证书」→ 申请 → 下载 | 得到 apiclient_cert.pem / apiclient_key.pem / apiclient_cert.p12，并记下证书序列号。用于退款、企业付款 |
| APIv3 密钥 | 「修改」→ 设置 | 退款 / v3 回调解密用（可选，建议一并设置） |
| 微信支付公钥 | 「管理公钥」→ 下载 | v3 回调验签用（可选） |
⚠️ 两个密钥别配错
APIv2 密钥和 APIv3 密钥是两个不同的东西，互不影响。密钥只显示一次（v2 设置后可查看），务必复制保存好。
05第四步：绑定 AppID 并配置授权域名（最关键）
入口商户平台 → 产品中心 → AppID 账号管理
这一步整个都在「AppID 账号管理」这块完成
包含两项：关联 AppID + 配置网页授权域名 / 授权目录。
5.1 关联 AppID
- 点绿色「+ 关联 AppID」。
- 填入你的服务号 AppID（从公众号后台查看，见第 06 步）。
- 到公众号后台 → 收到关联申请 → 点「同意」。
5.2 配置网页授权域名 / 授权目录
- 在同一块（AppID 账号管理）里，为已关联的 AppID 配置网页授权域名：填入你的访问域名。
- 同时确认 JSAPI 支付授权目录 已配置为该域名。
⚠️ 两个关键点
域名带不带
不做 5.1 的关联，下单会报
www 必须和你实际访问页面完全一致，否则报 10003 /「当前页面的URL未注册」。不做 5.1 的关联，下单会报
APPID_MCHID_NOT_MATCH，一分钱都收不了。
06第五步：公众号侧配置
入口https://mp.weixin.qq.com/
6.1 确认账号类型
请确保你的账户是 服务号，并且 已通过微信认证。
6.2 拿 AppID / AppSecret
- 路径：设置与开发 → 基本配置
- 记下「开发者 ID（AppID）」（
wx开头） - 点「开发者密码（AppSecret）」→ 重置 → 扫码验证 → 复制保存（只显示一次）
6.3 配 JS 接口安全域名
- 路径：设置 → 公众号设置 → 功能设置 → JS 接口安全域名
- 填入你的访问域名（示例
www.yunshangznkj.cn）。
「JS 这里一定要填写」——这是 H5 里微信 JS-SDK / 支付调起的前置项。
www.yunshangznkj.cn。6.4 配 IP 白名单
- 路径：设置与开发 → 基本配置 → IP 白名单
- 加入服务器出口 IP：
[平台出口 IP]（请在对接群 / 微信客服处获取；不加会报40164 invalid ip）
分工说明
网页授权域名已在第 05 步（商户平台 AppID 账号管理）配置，此处无需重复；公众号侧主要是 AppID/AppSecret、JS 接口安全域名、IP 白名单三项。
07第六步：到【我方商户后台】填写配置
登录商户后台（如 ysclubguanli.yunshang.cn）→ 左侧「微信配置」Tab。
7.1 「微信配置」Tab — 必要项（其余系统自动处理）
| 后台字段 | 填什么 | 从哪来 |
|---|---|---|
| 公众号 AppID | wx 开头的 AppID | 6.2 步 |
| AppSecret | 服务号密钥 | 6.2 步（重置后复制） |
| API v2 密钥 | 32 位密钥 | 第 04 步（下单+验签用，必填） |
| 商户号 | 一串数字 | 第 02 步（账户中心→商户信息） |
| 支付关联 AppID | 留空即可 → 系统自动取公众号 AppID | 第 05 步 |
| 证书序列号 / 私钥路径 / 证书路径 | 退款才需要；收款可不填 | 第 04 步 |
| 支付回调地址 | 留空即可 → 系统按你的域名自动生成 | — |
| 授权作用域 | 默认 snsapi_userinfo（系统预填） | — |
| 小程序 AppID / Secret | 有自有小程序才填（可选） | 小程序后台 |
| Mock 模式 | 关闭（正式生产） | — |
系统自动处理的部分（你不用填）
支付关联 AppID 留空 → 自动取 公众号 AppID（两者必须一致，系统已做一致性校验）·
支付回调地址 留空 → 按你的域名自动拼装 ·
授权作用域 → 默认 snsapi_userinfo。
敏感字段（AppSecret / API v2 密钥 / 证书路径）保存后不再回显；不修改就留空，留空 = 保留原值。
7.2 「品牌设置」Tab — 俱乐部数据
| 字段 | 填什么 |
|---|---|
| 俱乐部名称 / 品牌名 / 品牌标语 | 你的品牌信息（展示在 H5 顶部） |
| 品牌 LOGO | 上传图片（建议 2MB 内） |
| 认证标识 / 认证标签 | 如「官方认证」 |
绑定域名不在商户后台
域名由平台超管后台（俱乐部管理 → 绑定域名）统一绑定，你需要做的只是把域名告诉平台。绑定后用户访问该域名即自动加载你的 H5、注入你的微信收款配置。
7.3 保存并自检
- 点「保存配置」→ 提示"配置已保存"。
- 点「配置自检」→ 检查：公众号 AppID + Secret、API v2 密钥 + 商户号、Mock 模式。
- 全绿（Mock = 正式模式）即完成。
08系统做了什么（自动同步 / 动态关联）
1
平台超管绑定你的域名 → 写入
club.domain（唯一性校验）↓
2
域名 DNS 解析到平台服务器
[平台服务器地址]（由对接群提供）↓
3
用户访问你的域名 → 中间件按域名找到你的
club_id（找不到就 404，绝不串到别家）↓
4
你填的微信配置 → 系统做一致性严格校验（AppID / 商户号 / v2 密钥齐备，
pay_appid 与 oa_appid 一致）↓
5
下单 / 登录时按
club_id 读取配置，把 AppID / 商户号 / v2 密钥 动态注入到该域名的【JSAPI 支付】和【网页授权登录】请求↓
6
微信回调按你的「支付回调地址」路由回来，做验签 + 幂等置单
一句话
你在后台填一次，系统校验通过后按域名自动把配置注入到对应域名的收发请求，资金直接进你自己的账户。
09购买后的接入流程（官网套餐）
在官网完成套餐购买后，接入按以下顺序推进：
- 开通账号：平台为你在超管后台创建俱乐部账号，并绑定你的域名。
- 你按本教程配置：完成第 02–07 步（商户号、支付产品、API 安全、AppID 关联、公众号配置、后台填写）。
- 平台核验：核对域名解析与配置一致性（AppID / 商户号 / v2 密钥 / 授权域名）。
- H5 可访问（暂不可下单）：此时建议先不要挂载到菜单。
- 你配置前台内容：登录
ysclubguanli.yunshang.cn配置商品图、轮播图、营销信息、单子介绍、装修设置，以及是否开启累充 / 等级 / 特惠。 - 支付测试：配合技术人员做真实小额下单验证全链路。
- 正式上线：测试通过后挂菜单对外开放。
10提现（打手出金）：怎么开通、要交什么材料
打手接单赚的钱进「可提现余额」，提现由打手自己在 H5 发起；你只需要审核 + 打款。功能零配置即可用（线下打款模式）；想让系统自动转账到打手的支付宝/微信，按 10.2 把材料交给平台，由超管代你配置。
10.1 怎么运作（五步）
- 打手绑收款账户：H5「钱包 → 提现」里绑定支付宝 / 微信 / 银行卡 / 收款码（每种方式一个启用账户）。
- 打手发起提现：金额先冻结锁定（不能重复使用），默认每日最多 3 笔。
- 你审核：商户后台 → 财务 → 提现审核，通过 / 驳回（驳回金额自动退回打手）。
- 打款：未开通自动转账 = 你线下转账给打手（微信 / 支付宝 / 银行均可）；已开通 = 系统按审核结果自动转（见 10.2）。
- 确认到账：线下打款后在同一页面点「确认到账」登记完结（不做这一步打手的钱会一直冻结）。
10.2 开通「自动转账」：需要上交的材料
谁来配置密钥由平台超管代配，你把下列材料交给平台工作人员即可，不要填进商户后台。私钥文件请与密码分开、分两条消息发送；提交前建议加水印「仅供云上平台提现接入使用」。
支付宝（推荐主通道）：单笔默认 ≤ ¥5,000（商家平台可自助提到 ¥50,000）、实时到账、免费。到「商家平台（b.alipay.com）→ 资金管理」办理：
| 材料 | 在哪拿 / 怎么办 |
|---|---|
| 企业支付宝实名账号 + PID | 登录 b.alipay.com，「账户中心」查看（账户必须企业实名） |
| 开放平台 app_id | open.alipay.com 创建应用（绑定上面企业账户） |
| 应用私钥文件（RSA2，.pem） | 开发者中心「接口加签方式」生成——公钥证书模式，私钥文件自己留存后把文件交平台 |
| 支付宝公钥文件（或公钥证书） | 同上页面，用于平台核对转账回执 |
| 签约「单笔转账到支付宝账户」产品 | 商家平台 → 资金管理 → 转账（免费，需企业实名） |
| 转账场景「佣金报酬」声明 | 商家平台 → 转账场景里声明（无需额外材料） |
| 期望限额（单笔 / 单日） | 有提额后告知平台，同步调整系统自查限额 |
微信（适合小额，单笔默认只 ≤ ¥200）：到「商户平台（pay.weixin.qq.com）→ 产品中心 → 商家转账」申请：
| 材料 | 在哪拿 / 怎么办 |
|---|---|
| 「商家转账」产品权限 | 商户平台 → 产品中心 → 商家转账 → 申请开通（选择「佣金报酬」场景） |
| APIv3 密钥（32 位） | 账户中心 → API 安全（自己设置并保存，教程 04 步） |
商户 API 证书序列号 + apiclient_key.pem 私钥文件 | 教程 04 步已拿到，复制一份交平台 |
| 微信支付公钥 ID（PUB_KEY_ID_ 开头） | 账户中心 → API 安全 → 微信支付公钥 |
| 转账场景 ID | 权限开通后在「商家转账」功能页查看 |
微信限额提醒新版商家转账单笔默认只有 ¥200（单用户单日 ¥2,000），大额提现不适合走微信；提额需在商户平台申请、按平台审核结果为准。因此建议把支付宝作为主通道，微信留作小额奖励。
10.3 限额与规则（速查）
| 规则 | 说明 |
|---|---|
| 提现频率 | 每日 3 笔（被驳回的不占次数）；单笔最低 ¥10 |
| 风控 | 单日提现 > ¥2,000 或近 7 天 > ¥10,000 会触发冻结、转人工处理 |
| 支付宝出金 | 单笔 ≤ ¥5,000（可自助提额至 ¥50,000）、单日 ≤ ¥20,000、实时到账不可撤销 |
| 微信出金 | 单笔 ≤ ¥200（可申请提额）、单用户单日 ≤ ¥2,000、确认收款后到账 |
| 姓名实名 | 支付宝收款「姓名必须与实名一致」——不一致转账必失败（钱不会扣，自动退回打手） |
10.4 钱在哪 & 三个注意
- 钱始终在你自己的账户里：收款直连后充值款直达你的商户号/企业支付宝，出金也从同一账户打给打手，平台零垫资、不经手。
- 转账失败 ≠ 丢钱：姓名不符、超限额等会被渠道直接拒绝，金额自动解冻退回打手，修正账户后重新发起即可；系统异常则保持冻结等人工核查，绝不重复打款。
- 线下打款别忘「确认到账」：未开通自动转账时，打款后务必在后台点「确认到账」，否则打手的钱一直显示冻结，容易产生客诉。
11常见错误对照表
| 报错 / 现象 | 真因 | 怎么修 |
|---|---|---|
APPID_MCHID_NOT_MATCH | AppID 未与商户号关联 | 商户平台 → AppID 账号管理 → 关联 AppID |
40164 invalid ip | IP 白名单没加服务器 IP | 公众号后台 → IP 白名单加 [平台出口 IP]（对接群获取） |
10003 /「当前页面的URL未注册」 | 网页授权域名 / JSAPI 授权目录 域名形态不一致 | 域名带不带 www 与页面保持一致 |
签名错误 | API v2 密钥不对 | 核对 32 位 v2 密钥 |
| 订单一直「待支付」 | 支付回调地址不通 | 由平台核对自动生成的回调地址是否可达 |
| 无法网页授权 / 拿不到 openid | 账号是订阅号 | 换已认证服务号（订阅号无此能力） |
| 访问域名打开是别家 / 测试页 | 域名未绑定或解析错 | 联系平台超管核对域名绑定与 DNS 解析 |
A附录 A：后台字段 ↔ 微信侧来源 一览
| 后台字段 | 微信侧来源 |
|---|---|
| 公众号 AppID | mp.weixin.qq.com → 设置与开发 → 基本配置 → 开发者 ID |
| AppSecret | 同页 开发者密码（重置可见，只显示一次） |
| API v2 密钥 | pay.weixin.qq.com → 账户中心 → API 安全 → 商户 APIv2 密钥 |
| 商户号 | pay.weixin.qq.com → 账户中心 → 商户信息 |
| 支付关联 AppID | pay.weixin.qq.com → 产品中心 → AppID 账号管理 |
| 网页授权域名 | pay.weixin.qq.com → 产品中心 → AppID 账号管理（AppID 这块） |
| JSAPI 支付授权目录 | pay.weixin.qq.com → 产品中心 → AppID 账号管理 |
| JS 接口安全域名 | mp.weixin.qq.com → 公众号设置 → 功能设置 |
| IP 白名单 | mp.weixin.qq.com → 设置与开发 → 基本配置 |
| 证书序列号 / 私钥 / 证书路径 | pay.weixin.qq.com → 账户中心 → API 安全（退款用） |
| 绑定域名 | 平台超管后台（俱乐部管理 → 绑定域名），商户后台无此入口 |
微信侧人工项（系统代填不了）
- ☐ 商户平台 → AppID 账号管理 → 关联 AppID（绑定服务号 AppID）
- ☐ 商户平台 → AppID 账号管理 → 配置网页授权域名 = 你的域名
- ☐ 商户平台 → AppID 账号管理 → JSAPI 支付授权目录 = 你的域名（形态与页面一致）
- ☐ 公众号后台 → JS 接口安全域名 = 你的域名
- ☐ 公众号后台 → IP 白名单加
[平台出口 IP]（对接群获取）
B附录 B：配置一致性校验（平台侧）
为保证"填了就能用"，后端在保存与下单前做严格一致性校验：
| 校验项 | 规则 | 不满足时 |
|---|---|---|
| 收款四要素齐备 | oa_appid + pay_appid + pay_mch_id + apiv2_key 均非空 | fail-closed，拒绝下单并提示缺项 |
| AppID 命名空间一致 | pay_appid 必须等于 oa_appid（否则 openid 不属于支付 AppID 命名空间） | 拒绝下单，提示"支付 AppID 与公众号 AppID 不一致" |
| 商户号格式 | 纯数字 | 保存时拦截 |
| AppID 格式 | ^wx[0-9a-f]{16}$ | 保存时拦截 |
| v2 密钥长度 | 32 位 | 保存时拦截 |
| Mock 模式 | 生产环境必须为关闭 | 自检提示 |