📚 课程目录第1章支付SDK集成前置条件

1. 支付SDK集成前置条件：环境要求、账号权限、商户密钥、依赖库版本检查清单

1.1 适用场景

本流程适用于所有需要将支付SDK集成至后端服务（如Java/Python/Node.js）或移动端（Android/iOS）的系统集成场景。执行本流程能确保集成环境满足SDK运行的最低要求，避免因环境不匹配导致的后续配置失败、签名校验失败或运行时崩溃。

1.2 前置条件

已从支付服务商（如微信支付、支付宝、银联等）获取集成资格，并开通相应产品权限。
拥有服务商管理后台的访问权限（至少为操作员级别）。
准备好用于存放SDK安装包及配置文件的干净开发/测试环境，操作系统、JDK/Python版本等满足后续检查要求。
确认网络策略允许设备访问支付服务商的API网关域名（如 api.mch.weixin.qq.com）。

1.3 操作步骤

步骤1：检查运行环境

检查项	最低要求	验收方式
操作系统	Linux CentOS 7+/Ubuntu 18.04+，macOS 10.15+，Windows Server 2016+	`cat /etc/os-release # Linux sw_vers # macOS winver # Windows`
JDK（Java SDK）	JDK 8u202 或更高版本（推荐 JDK 11 LTS）	`java -version`
Python（若使用Python SDK）	Python 3.8+	`python3 --version`
Node.js（若使用Node SDK）	Node.js 14+ LTS	`node --version`

提示： 推荐在容器（Docker）中统一开发环境，避免多项目依赖冲突。基础镜像可选用 openjdk:11-jre-slim 或 python:3.9-slim。

步骤2：确认账号权限与API证书

登录支付服务商管理后台，进入「开发者中心」或「账户中心」。
检查当前（商户密钥）状态是否为“启用”，且未绑定IP白名单（或已将本机IP加入白名单）。
如使用证书认证（如微信支付V3版），下载商户证书（.p12 或 .pem + .key），并记录证书序列号。
确认开发者账号已被授予“支付接口调用”权限，部分平台需要额外申请“退款”、“查询”等细分权限。

注意： 生产环境建议使用独立子商户号，避免主商户号密钥泄露导致资金风险。密钥不允许明文存于代码仓库，应使用环境变量或密钥管理服务。

步骤3：获取商户密钥（ / Secret）

记录以下凭证信息，并存储至安全位置：

商户号（mch_id）：服务商分配的唯一商户标识。
（key）：用于签名计算，长度通常为32字节，格式为十六进制或ASCII字符串。
APIv3 密钥（apiv3_key）：微信支付V3版使用，用于解密回调报文。
平台证书公钥：用于验签，需定期从服务商下载更新。

示例密钥配置（仅用于测试环境）：

# 微信支付商户平台 - 商户密钥信息
mch_id: "1230000109"
: "ABCDEF1234567890ABCDEF1234567890"
apiv3_key: "YourAESKeyMustBe32BytesLong!"
cert_serial_no: "1234567890ABCDEF"

步骤4：检查依赖库版本

根据所选SDK语言的依赖管理工具，执行版本检查命令并验证是否满足SDK要求。以下为常见版本约束示例：

SDK类型	依赖库/框架	最低版本	检查命令
Java SDK (Maven)	`com.github.wechatpay-apiv3`	0.2.11	`mvn dependency:list \| grep wechatpay`
Java SDK (Gradle)	`com.github.wechatpay-apiv3`	0.2.11	`gradle dependencies \| grep wechatpay`
Python SDK	`wechatpayv3`	0.13.0	`pip show wechatpayv3`
Node.js SDK	`wechatpay-node-sdk`	3.0.0	`npm list wechatpay-node-sdk`

1.4 输入输出物

类别	输入物	输出物
环境配置	操作系统镜像/基础Dockerfile	已验证的运行环境（可通过`docker images`或`env`确认）
账号权限	服务商管理后台登录凭证	、商户号、证书文件
依赖库	`pom.xml` / `build.gradle` / `requirements.txt` / `package.json`	解析后的依赖树，版本满足约束

1.5 责任边界

系统集成方：负责提供开发环境、账号权限申请、密钥安全存储、依赖版本锁定。
支付服务商对接团队：审核集成方服务器IP、发放商户证书、提供最新SDK版本及兼容性说明。
项目测试负责人：验收前置检查结果，并在测试环境发起一笔1分钱交易验证连通性。
运维团队：确保生产环境与测试环境配置一致，密钥通过机密管理系统（如HashiCorp Vault）下发。

1.6 记录材料

执行完成后应生成以下文档/记录：

《前置条件检查清单》：逐项记录环境、权限、密钥、依赖库的检查结果，并签字确认。
密钥分发记录：记录密钥首次下载时间、颁发者、接收者，以及密钥生命周期管理策略。
SDK版本兼容性矩阵：整理SDK版本号、对应依赖库版本、已知兼容问题及规避方法。

1.7 异常处理

异常现象	可能原因	处理措施
环境检查命令返回“command not found”	JDK/Python未安装或PATH未配置	安装对应运行时并配置环境变量
验证失败（签名错误）	密钥与商户号不匹配 / 密钥已过期	在管理后台重新生成密钥并更新配置
证书序列号不匹配	下载的证书文件与后台登记的序列号不一致	重新下载证书并核对序列号，如仍不匹配联系技术支持
依赖库下载失败	镜像源不可用 / 版本号不存在	切换至官方镜像源（如阿里云Maven镜像）或指定确切版本号

1.8 验收标准

[ ] 运行环境检查项全部通过（操作系统版本、JDK/Python版本等）。
[ ] 账号权限设置正确，可成功获取商户号、、证书文件。
[ ] 密钥文件已加密存储至安全位置，未明文暴露于代码仓库或日志。
[ ] 依赖库版本均满足SDK要求，并锁定至可重复构建的快照版本。
[ ] 在测试环境执行 curl 模拟请求，返回HTTP 200且JSON响应正常（示例命令如下）。

# 示例：使用密钥进行HTTP GET请求（微信支付查单接口）
curl -X GET "https://api.mch.weixin.qq.com/v3/pay/transactions/id/421000000000000000000000000000000?mchid=1230000109" \
  -H "Authorization: WECHATPAY2-SHA256-RSA2048 ..."

验收人确认签字后，进入SDK代码集成阶段。