第1章 支付SDK能力概览与接入前的技术评估
1.1 能力概览
支付SDK是企业对接线上收银、资金结算、分账与退款的核心技术组件。在开始集成之前，必须首先明确SDK的能力边界：它支持哪些支付渠道，提供哪些功能矩阵，以及在什么技术环境下运行。
核心原则： 不是所有SDK都适合所有场景。选择前应完成能力匹配、依赖检查和选型边界确认，否则后期会因功能缺失或版本冲突导致返工。
1.1.1 支持支付渠道
主流支付SDK通常覆盖以下渠道（以国内通用聚合支付为例）：
- 支付宝 + 微信支付（必选核心渠道）
- 银联云闪付 / 银联网关（合规备选）
- QQ钱包 / 京东支付 / 百度钱包（辅助渠道，视业务区域）
- 境外渠道：海外银行卡、PayPal、iDEAL、Sofort（仅针对跨境场景）
1.1.2 功能矩阵
| 能力域 | 能力项 | 说明 |
|---|---|---|
| 支付 | 扫码支付 / 公众号/小程序支付 / App内支付 / H5支付 / 刷脸支付 | 支持同步（支付即返回）与异步（回调通知）两种结算模式 |
| 退款 | 全额 / 部分退款，原路退回 | 需支持重入幂等和退款状态反查 |
| 对账 | 每日交易明细文件下载 / 实时流水同步 | 用于商户侧财务系统对平 |
| 签约 | 委托代扣 / 免密签约 / 协议支付 | 用于周期性扣款场景（会员订阅、水电缴费） |
| 风控 | 交易评分、频次限制、黑名单 | 可选能力，部分SDK内置基础规则引擎 |
1.2 技术选型边界
技术选型边界决定了SDK能否在你当前的技术栈中正确编译、运行并保持长期可维护性。常见的边界评估维度包括：
- 语言 & 运行时版本：Java 8/11/17、PHP 7.4/8.x、Python 3.6+、Go 1.18+、Node.js 14+
- 通信协议：HTTP/1.1、HTTPS、gRPC、WebSocket（较少见）
- 数据格式：严格遵循 JSON / XML / Protobuf 其中一种
- 签名算法：RSA2(SHA256withRSA)、HMAC-SHA256、国密SM2/SM3
- 线程模型：同步阻塞、异步非阻塞、响应式（Reactive）
常见陷阱： 某些SDK在 Java 11 上强制依赖 Jakarta EE，与旧版 javax 不兼容。务必先执行编译测试，不要只看文档兼容列表。
1.3 环境要求
在接入前必须完成以下环境准备与验证：
| 环境项 | 要求 | 验证命令/检查点 |
|---|---|---|
| 操作系统 | Linux (CentOS 7+/Ubuntu 20.04+) / macOS (Monterey+) / Windows Server 2019+ | uname -a / cat /etc/os-release |
| 运行环境 | JDK 8u202+ / PHP 8.0+ / Python 3.8+ / Go 1.20+ | java -version / php -v / python --version |
| 依赖管理 | Maven / Gradle / Composer / go mod / npm | mvn -v / composer --version |
| 网络 | 出网权限（HTTPS 443），可访问支付网关域名 | curl -I https://api.pay.example.com |
| 时间同步 | NTP 同步，与支付网关时间偏差 < 300秒 | timedatectl show -p NTPSynchronized |
# 服务端时间同步验证示例
#
# 1. 检查NTP同步状态
timedatectl show -p NTPSynchronized
# 预期输出: NTPSynchronized=yes
# 2. 对比本地时间与标准时间（取差值）
curl -s http://worldtimeapi.org/api/timezone/Etc/UTC | python -c "import sys,json; d=json.load(sys.stdin); print('差:', d['datetime'])"
1.4 接入前评估清单
以下评估应在编码前完成，并记录在项目技术评估文档中：
- 确定所需支付渠道及其对应的商户号/AppID。
- 确认商户平台的签名密钥对已配置并启用 RSA2 或 SM2。
- 准备异步回调域名（必须为 HTTPS，且公网可访问）。
- 确认开发环境的编译工具链与依赖版本（Maven/Gradle/Composer + JDK/PHP版本）。
- 确定 SDK 的包名/组织名，并添加到依赖管理文件。
- 获取沙箱环境的测试密钥与 Mock 回调 URL。
- 确认支付结果通知的 幂等处理方案（基于通知ID去重）。
1.5 支付SDK集成架构图
下图展示了从商户后端到支付网关的核心交互流程与技术选型边界，在实际集成前应确保每个环节的能力和版本都匹配。
1.6 依赖管理与SDK引入
在完成评估后，即可在项目中添加SDK依赖。以下以Maven（Java）和Composer（PHP）为例：
<!-- Java Maven 依赖示例 （假设SDK groupId: com.pay.sdk） -->
<dependency>
<groupId>com.pay.sdk</groupId>
<artifactId>pay-sdk-core</artifactId>
<version>3.2.5</version>
</dependency>
<!-- 可选：对账/通知模块 -->
<dependency>
<groupId>com.pay.sdk</groupId>
<artifactId>pay-sdk-reconciliation</artifactId>
<version>3.2.5</version>
</dependency>
// PHP Composer 依赖示例
// composer.json 片段
{
"require": {
"pay/sdk-core": "^3.2",
"pay/sdk-notification": "^3.2"
}
}
// 然后执行: composer install
实践建议： 在沙箱环境先执行一次完整的
集成测试，模拟支付创建 → 回调接收 → 结果查询三个原子流程，以验证SDK的入参、签名、回调验签是否全部正确。
1.7 回调验签初始化
SDK初始化时需显式配置回调验签公钥。以下为商户端回调处理器的启动配置示例（Java）：
// 1. 初始化SDK客户端
PayClientConfig config = new PayClientConfig();
config.setAppId("wx2024123456789");
config.setPrivateKey("-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----");
config.setPayPublicKey("-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"); // 支付网关公钥
config.setNotifyUrl("https://your-domain.com/api/pay/callback");
config.setSignType(SignType.RSA2);
// 2. 注册回调处理器
PaySdk sdk = new PaySdk(config);
sdk.registerNotifyHandler((request) -> {
// 验签由SDK内部自动完成
// 验签通过后返回解析后的订单对象
PayNotifyResult result = sdk.parseNotify(request);
// 业务处理...
return result.getCode().equals("SUCCESS");
});
sdk.start();
至此，已完成支付SDK能力概览与技术评估的全部内容。接下来请进入第2章——沙箱环境配置与商户密钥创建。