一、前期准备与选型
1.1 了解银联支付接口的定位与版本
在进行企业级支付集成前，明确银联支付接口的定位与支持的版本是首要步骤。对于Java开发者而言，关注对接版本、API风格、回调机制以及是否存在版本迁移的路标，可以避免后续重复工作。
此外，结合自身业务场景（如二维码支付、手机钱包、网页支付等）来选择合适的接口通道，能提升集成效率与后续运维能力。对接前应形成清晰的接口清单和数据字段清单，以便在实现时有明确的边界。
1.2 申请商户号与证书类型
银联支付通常需要商户号、商户私钥证书、以及公钥证书等信息。提前准备好签名证书和证书文件的存放路径，有助于在开发阶段就完成数据签名与验签逻辑的实现。
在申请阶段，需确认证书类型、有效期、证书格式（PFX/PKCS12、CER等）以及证书的更新策略，以避免上线后出现证书失效导致的接口调用失败。
二、接入资质与商户配置
2.1 商户号、商户信息配置
为了实现正确的交易路由与对账，商户号、商户名称、联系人信息、客服电话等信息需要在对接平台官网完成配置。确保对公网域名的白名单与回调地址匹配，以防止回调请求被拦截。
在代码层面，建议把关键配置项（如商户号、接口地址、证书路径）放到独立的配置信息源，例如环境变量或配置中心，便于不同环境的区分和版本化管理。
2.2 接口域名和回调地址配置
银联支付的回调地址通常用于接收交易结果通知，需要确保回调地址可达、且具备HTTPS加密。在集成阶段，应测试同步下单回执与异步通知的路径是否正确映射到业务系统。
为提升鲁棒性，可以在回调处理过程中加入签名验签、重放保护、幂等控制等机制，确保通知的安全与准确。
三、开发环境与接口规范
3.1 接口协议与传输格式
银联支付通常采用HTTP/HTTPS传输、JSON或自定义文本协议的接口调用。明确参数字段、必填项、字段长度与编码规则，能显著降低字段错误导致的交易失败。
在实现时，请关注接口版本号、时间戳、签名字段的组织方式，确保请求体在服务端可被正确解析与验签。
3.2 证书加载和签名算法
签名与证书是支付对接的核心安全要素。加载私钥证书、构造待签名字符串、执行签名，以及在服务端进行验签，构成了完整的安全链。
为提高安全性，应采用SHA256withRSA或SHA256withECDSA等强签名算法，并对签名字符串的格式进行统一约定，避免因空格、字符编码等差异导致验签失败。
四、核心支付流程实现
4.1 下单与请求组装
核心步骤是将前端传递的订单信息转换为符合银联规范的请求体，并在发送前完成<签名、证书绑定等准备工作。对接时应确保商户号、订单金额、币种、交易类型、回调URL等字段的正确性。
在实现阶段，建议把请求组装与签名逻辑分层，便于测试与维护，同时对敏感字段进行最小化暴露，提升系统安全性。
import java.util.Map;
import java.util.TreeMap;
import java.util.Base64;
import java.security.Signature;// 示意：组装并签名一个下单请求
public class UnionPayOrderRequest {public static String signRequest(Map params, PrivateKey privateKey) throws Exception {// 1) 排序并拼接成 data=val&data2=val2...String data = params.entrySet().stream().filter(e -> e.getValue() != null && !e.getValue().isEmpty()).sorted(Map.Entry.comparingByKey()).map(e -> e.getKey() + "=" + e.getValue()).collect(java.util.stream.Collectors.joining("&"));// 2) 使用 SHA256 with RSA 签名Signature signer = Signature.getInstance("SHA256withRSA");signer.initSign(privateKey);signer.update(data.getBytes("UTF-8"));byte[] signBytes = signer.sign();return Base64.getEncoder().encodeToString(signBytes);}// 额外：示例如何把参数传入与签名结果组合成最终请求体（伪代码）public static Map buildSignedRequest(Map baseParams, PrivateKey key) throws Exception {String signature = signRequest(baseParams, key);Map signed = new TreeMap<>(baseParams);signed.put("signature", signature);return signed;}
}
以上示例展示了一个简化的签名流程，实际对接需结合银联提供的具体字段与签名规范进行实现。
4.2 支付结果查询与轮询
完成下单后，需要调用查询接口获取交易状态，以确认支付结果并更新本地订单表。应设置幂等性处理，避免重复扣款或重复通知引发业务混乱。
在查询阶段，关注交易状态码、超时策略、重试间隔等参数，确保在网络异常时可安全重试并记录日志。
import java.net.http.*;
import java.net.URI;
import java.time.Duration;// 简化的查询示例
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder().uri(URI.create("https://gateway.unionpay.com/pay/query")).timeout(Duration.ofSeconds(10)).POST(HttpRequest.BodyPublishers.ofString("{\"orderId\":\"ABC123\"}")).header("Content-Type", "application/json").build();HttpResponse resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());
五、退款、撤销与对账
5.1 退款/撤销接口
对于已支付的订单，退款接口与撤销接口是常见的场景。实现时应确保退款金额、订单号、原交易流水号、退款原因等字段完整且一致。
同时，需要在系统中建立退款幂等性控制，避免因多次请求而造成资金异常与对账混乱。
5.2 对账文件与日常对账流程
日常对账是支付体系稳定性的关键环节。应定期获取对账文件、日清日结报表，并在本地对账系统中实现<交易状态、金额、币种、商户号等字段比对。
对账过程中要留意对账差异处理流程、异常订单标记与人工复核，确保财务数据的一致性与可追溯性。
// 伪代码：简单对账比对逻辑示例
public class Reconciliation {public boolean compare(Transaction t, BankRecord r){return t.getOrderId().equals(r.getOrderId())&& t.getAmount() == r.getAmount()&& t.getCurrency().equals(r.getCurrency())&& t.getStatus().equals(r.getStatus());}
}
六、测试与上线注意事项
6.1 测试环境与沙盒
在正式环境前，务必在测试环境/沙盒中完成全流程的端到端验证，覆盖下单、支付、查询、退款、通知回调等场景。
测试阶段应启用日志追踪、断点排查、模拟网络异常来评估系统的健壮性与容错能力。
6.2 上线切换与监控
上线时应实现逐步放量、灰度发布、回滚策略，并配置丰富的监控指标，例如接口响应时间、错误率、日志告警，以便快速发现并修复问题。
另外，证书轮换与密钥管理机制应在上线计划中明确，避免因证书失效导致交易中断。
import javax.net.ssl.SSLContext;
import java.security.KeyStore;
import java.security.cert.X509Certificate;
import java.net.http.HttpClient;// 示意：基于双向TLS的HttpClient初始化
public class HttpClientFactory {public static HttpClient create() throws Exception {KeyStore ks = KeyStore.getInstance("PKCS12");try (var in = new java.io.FileInputStream("path/to/keystore.p12")) {ks.load(in, "keystorePassword".toCharArray());}SSLContext sslContext = SSLContextBuilder.create().loadKeyMaterial(ks, "keyPassword".toCharArray()).loadTrustMaterial(ks, (chain, authType) -> true).build();return HttpClient.newBuilder().sslContext(sslContext).build();}
}
