工行聚合支付二维码全流程开发指南：从生成到退款实战解析-优快云博客

1. 工行聚合支付二维码，到底是个啥？

如果你正在开发一个需要收款的线上商城、线下门店小程序，或者是一个活动报名缴费系统，那么“支付”这个环节你一定绕不过去。自己做一套支付系统？那太不现实了，安全、合规、资金清算，每一个都是大坑。所以，我们通常选择接入像工商银行这样的金融机构提供的聚合支付服务。

工行聚合支付二维码，简单来说，就是工商银行提供的一套“收款工具包”。它把微信支付、支付宝、银联云闪付等多种支付渠道，打包成了一个统一的接口。对于你（开发者）和你的商户来说，好处是显而易见的：你只需要对接工行一家，用户却可以用几乎所有主流的支付方式来完成付款。你不用再分别去申请微信支付、支付宝的商户号，也不用写好几套不同的支付逻辑，省时省力。

这个“工具包”的核心，就是二维码。它主要支持两种支付场景：

主扫支付（用户扫你）：你在收银台、网页或者App里生成一个支付二维码，用户打开手机上的微信或支付宝，扫这个码完成支付。这适合线上商城、自助售货机等场景。
被扫支付（你扫用户）：用户出示他的微信/支付宝付款码，你用扫码枪或者手机摄像头去扫这个码，完成扣款。这适合超市、便利店、餐厅等线下面对面收银的场景。

这篇文章，我就以一个过来人的身份，手把手带你走通工行聚合支付二维码的全流程开发。从最开始的申请接入、生成二维码，到处理支付结果、处理退款，甚至是一些调试中容易踩的坑，我都会结合真实的代码示例，掰开揉碎了讲给你听。目标就是让你看完之后，能真正把功能跑起来，而不是只停留在“知道有这么回事”的层面。

2. 动手之前：环境与材料准备

在开始敲代码之前，有几件“硬装”工作必须完成。这就像装修房子，水电没通，再好的设计也白搭。

2.1 申请与配置：拿到你的“开发钥匙”

首先，你需要去工商银行的开放平台（open.icbc.com.cn）注册成为开发者，并申请开通“聚合支付”产品。这个过程需要提交企业相关资料，有一定的审核周期，建议提前准备。

审核通过后，你会拿到几样至关重要的“钥匙”：

AppId：你的应用在工行平台的唯一标识。
商户号（Mer_ID）：你在工行体系内的商户身份编号。
公私钥对：这是安全通信的基石。你需要在工行平台生成一对RSA密钥，将公钥上传到平台，而私钥则必须妥善保存在你的服务器上，绝不能泄露。后续所有的请求签名验证都靠它。
API网关地址：所有接口调用的统一入口，通常是 https://gw.open.icbc.com.cn/api/。

我建议你在项目里专门建一个配置类来管理这些信息，比如叫 ICBCPayConstants。别把这些敏感信息硬编码在业务逻辑里，最好放在配置文件（如 application.yml）中，方便不同环境（开发、测试、生产）切换。

// 示例：一个简单的配置类
public class ICBCPayConstants {
    // 从配置文件中注入，这里用静态变量示例
    public static String AppId = "你的AppId";
    public static String Mer_ID = "你的12位或15位商户号";
    public static String Store_Code = "你的e生活档案编号"; // 如有
    public static String SIGN_TYPE_RSA2 = "RSA2";
    public static String private_key = "-----BEGIN PRIVATE KEY-----\n你的私钥内容\n-----END PRIVATE KEY-----";
    public static String public_key = "-----BEGIN PUBLIC KEY-----\n你的公钥内容\n-----END PUBLIC KEY-----";

    // API地址
    public static String generateQrcodeURL = "https://gw.open.icbc.com.cn/api/qrcode/V2/generate";
    public static String scanPayURL = "https://gw.open.icbc.com.cn/api/qrcode/pay/V4";
    public static String queryPayResultURL = "https://gw.open.icbc.com.cn/api/qrcode/query/V5";
    public static String payRejectURL = "https://gw.open.icbc.com.cn/api/qrcode/V2/reject";
    public static String queryRejectResultURL = "https://gw.open.icbc.com.cn/api/qrcode/reject/query/V3";
    // 注意：冲正接口地址请以最新文档为准
}

2.2 工行SDK：你的“瑞士军刀”

工行提供了官方的Java SDK，这能极大简化我们的工作。你不需要自己去组装复杂的请求报文、计算签名、处理加密解密。SDK把这些脏活累活都封装好了。

你需要去工行开放平台的文档中心，找到聚合支付二维码的SDK下载链接。下载后，将其引入到你的项目中。如果你使用Maven，可以将SDK的Jar包安装到本地仓库，或者上传到公司私服，然后在 pom.xml 中依赖它。

<!-- 示例：假设SDK的groupId和artifactId，具体以你下载的SDK为准 -->
<dependency>
    <groupId>com.icbc.openapi</groupId>
    <artifactId>icbc-api-sdk</artifactId>
    <version>最新版本</version>
</dependency>

引入SDK后，核心的“工具”就是 DefaultIcbcClient 这个类。我们后续所有接口调用，都会通过它来完成。初始化它需要上面准备好的AppId、签名类型、私钥和工行公钥。

3. 核心实战一：生成收款二维码（主扫支付）

这是最常用的场景。用户在你这儿选好商品，点击支付，你的后台生成一个二维码图片展示给用户，用户扫码付钱。

3.1 接口调用与参数详解

生成二维码的接口地址是：/api/qrcode/V2/generate。调用这个接口，核心是构造两个对象：请求客户端（DefaultIcbcClient）和请求内容（QrcodeGenerateRequestV2Biz）。

我结合代码，把几个关键参数给你讲透：

@Service
public class IcbcPayServiceImpl implements IcbcPayService {
    private static final Logger logger = LoggerFactory.getLogger(IcbcPayServiceImpl.class);

    @Override
    public Map<String, Object> generateQrcode(Map<String, Object> orderData) {
        // 1. 初始化客户端（建议复用，不要每次创建）
        DefaultIcbcClient