PAX A910 调用 doTransaction() 出现 SSL Error 2303

2026-10-24支付老李

结论

Error 2303 出现在 TLS 握手阶段，与 doTransaction() 的业务参数无关。connection callback 返回成功，通常只表示 TCP socket 已建立，不代表证书校验已经通过。

异常中的证书主题属于 Pine Labs，但仅凭主题信息还无法判断具体原因。常见情况有：

PoSLib 1.6.0 内置的信任证书与终端证书不匹配。
PAX A910 上的 MasterApp、固件或证书包与 SDK 不兼容。
终端证书已过期、尚未生效或证书链不完整。
Android 设备的日期、时间或时区错误。
使用 IP 地址连接时，证书中的 SAN/CN 与连接地址不匹配。
当前 IP 或端口不是终端实际开放的本地集成服务地址。

修改交易代码通常解决不了这类问题。应先确认终端的本地网络地址和端口，再请 Pine Labs 或终端服务商核对 SDK、MasterApp、固件和证书配置。

为什么显示 Connected，交易时仍然失败

一些 SDK 会分两步建立连接：

建立 TCP/IP 连接。
首次发送交易请求时建立 TLS 会话并校验证书。

因此，下面这些状态可能同时出现：

socket 连接成功；
connection callback 执行成功；
UI 显示 Connected；
doTransaction() 在 TLS 握手时失败。

这些状态并不冲突。它们只能证明目标地址的 8094 端口接受了连接，无法证明连接的是正确服务，也无法证明 SDK 信任服务端证书。

首先检查硬编码地址

103.215.234.21 看起来是公网地址，不是常见的局域网地址。PAX A910 与 Android 设备连接同一 Wi-Fi 时，其地址通常属于以下局域网网段：

192.168.x.x
10.x.x.x
172.16.x.x - 172.31.x.x

除非 Pine Labs 明确要求使用 103.215.234.21:8094，否则不要把文档示例、云端地址或其他环境的地址当成终端地址。

请在 PAX A910 的网络设置或 MasterApp 配置页面中直接确认：

当前 Wi-Fi IP 地址；
Local Integration 是否已启用；
实际监听端口；
终端和 Android 应用是否处于同一子网；
Wi-Fi 是否启用了 AP/client isolation；
网络中是否存在 VPN、代理、防火墙或企业访问控制。

如果硬编码地址指向了错误的服务，即使 TCP 连接成功，服务端证书也可能不符合 PoSLib 的预期。

建议的排查顺序

1. 校准系统时间

同时检查 Android 设备和 PAX A910 的以下设置：

日期；
时间；
时区；
自动网络时间。

如果证书尚未生效或已经过期，设备时间出现偏差会直接导致 TLS 握手失败。

2. 获取完整异常链

不要只记录 Error 2303，还应输出最底层的 cause，以便区分证书过期、信任链失败和主机名不匹配。

try {
    posLib.doTransaction(transactionRequest);
} catch (Exception e) {
    Throwable cause = e;
    while (cause != null) {
        Log.e(
            "PoSLib",
            cause.getClass().getName() + ": " + cause.getMessage()
        );
        cause = cause.getCause();
    }
}

重点查找以下信息：

CertPathValidatorException
Trust anchor for certification path not found
CertificateExpiredException
CertificateNotYetValidException
No subject alternative names present
Hostname verification failed
protocol_version
handshake_failure

相比 Error 2303，这些底层错误更能反映实际原因。

3. 核对终端版本和证书状态

向 Pine Labs 或负责部署终端的服务商提供：

PAX A910 序列号；
TID/MID；
PoSLib 版本：1.6.0；
Android 版本；
MasterApp 名称和完整版本号；
终端固件版本；
Local Integration 配置截图；
连接使用的 IP 和端口；
完整异常堆栈；
问题发生时间和时区。

请对方确认：

当前 MasterApp 是否支持 PoSLib 1.6.0；
终端是否已启用 ECR/Local Integration；
终端证书是否已正确下发、激活或更新；
SDK 是否要求使用特定证书包；
当前商户是否已开通 QR、NFC、刷卡等交易能力。

仅凭 “PAX A910 + PoSLib 1.6.0” 无法推断出一个通用的兼容版本。兼容性还取决于 MasterApp、固件、部署环境和证书批次，应以 Pine Labs 针对该终端提供的兼容矩阵为准。

4. 单独排查 discovery 问题

scanOnlinePOSDevice() 失败和 SSL 错误不一定来自同一个问题。局域网发现通常依赖广播或组播，可能受以下因素影响：

两台设备连接了不同的 SSID、VLAN 或访客网络；
无线接入点启用了客户端隔离；
Android 应用缺少网络或组播相关权限；
路由器屏蔽了 UDP broadcast/multicast；
终端没有启用 Local Integration 或 discovery 服务；
防火墙阻止了发现端口。

应根据 SDK 文档和目标 Android 版本检查 Android 清单中的相关权限，至少包括：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

Bluetooth discovery 还需要根据 Android 版本申请相应权限。Android 12 及以上版本通常涉及：

<uses-permission
    android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" />

<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

这些权限需要按需在运行时申请。旧版 Android 可能还需要旧的 Bluetooth 权限或定位权限，具体以 PoSLib 文档和应用的 targetSdkVersion 为准。

不建议采用的处理方式

不要用以下方法绕过证书校验：

安装“信任所有证书”的 TrustManager；
关闭 HostnameVerifier；
修改应用，使其接受任意服务端证书；
未核实来源就把异常中的证书直接加入全局信任；
降低 TLS 安全级别。

下面这类代码即使能让握手继续，也会让支付链路失去身份验证能力，不应在生产环境中使用：

// 不要使用接受所有证书的 TrustManager。

此外，Android 的 network_security_config 通常只能影响应用通过系统网络栈建立的连接。如果 PoSLib 在内部创建自己的 SSLContext、trust store 或证书 pinning，修改这项配置也无法解决问题。

关于 certificate provisioning

PAX A910 是否需要额外 provisioning，取决于 Pine Labs 的部署方式。商户应用通常不应自行生成或替换支付终端证书。终端证书、根证书链、密钥注入和 MasterApp 配置一般都属于受控部署流程。

如果终端尚未完成部署、证书轮换失败，或安装了不匹配的 MasterApp，应由 Pine Labs 或授权服务商重新下发配置。不要自行复制其他终端的证书或私钥。

当前最应优先确认两件事：一是 103.215.234.21:8094 是否确实为这台 PAX A910 的本地集成地址，二是请 Pine Labs 根据终端序列号核对 PoSLib 1.6.0、MasterApp、固件和证书包之间的兼容关系。