通联支付套件

<div hidden="">AI抽取开始标记</div>

# Allinpay SYB Java SDK

通联支付收银宝SDK

## 一、简介

1. 本文主要介绍收银宝系统 Java SDK的接入。 SDK支持的模块主要包括：
- 商户管理：商户进件、商户信息管理、商户活动报名、微信子商户参数配置等；
- 交易：扫码支付、JS、小程序、线上支付（快捷、网关）、云闪付API（无感、云微、签约支付）等；
- 账户管理：账户结算，账户余额、历史余额、投资额度等；
- 行业方案：协同收银、分账等；

2. 使用通联支付 收银宝SDK，你将体验到以下优势：
- 快速接入：SDK 封装了接口请求、签名、验证、加密等逻辑，开发者只需简单调用 SDK 提供的类和方法即可完成接入，无需处理签名验签和网络请求等底层逻辑
- 提高代码质量：SDK 在设计之初就考虑到易用性、安全性和扩展性，致力帮助开发者避免一些复杂的逻辑编写和一些常见又容易忽略的注意细节
- 方便升级和维护：当接口升级时，开发者仅需更新 SDK 即可使用新接口，无需修改业务代码，轻松应对接口变更带来的影响

## 二、环境要求
- 适用JDK 版本 1.8 及以上的开发环境

## 三、SDK版本记录
| 版本    | 日期         | 版本说明          |
|:------|:-----------|:--------------|
| 1.1.0 | 2025/12/02 | 新增应用服务商API接口；新增H5收银台API接口；新增支持RSA2算法 |
| 1.0.1 | 2025/11/12 | 优化支付客户端构建方式 |
| 1.0.0 | 2025/10/29 | 初始版本          |

## 四、接入流程
接入主要分为以下步骤：
1. 接入前准备
   1. 提交商户材料完成进件及相关业务配置；
   1. 登录商户服务平台配置对接参数，参见[《收银宝对接参数配置》](https://prodoc.allinpay.com/doc/2316/)；
1. 安装
   1. 软件包仓库 [Maven Central](https://central.sonatype.com/artifact/com.allinpay.cus.sdk/allinpay-syb-sdk-java)
   2. 使用包管理系统，例如 Maven、Gradle，快速添加通联支付官方 SDK。
      
      如果你使用的是 Gradle，请在 build.gradle 中加入：
      ```
      implementation("com.allinpay.cus.sdk:allinpay-syb-sdk-java:${VERSION}")
      ```

如果你使用的是 Maven，请在 pom.xml 中加入：
      ```
      <dependency>
          <groupId>com.allinpay.cus.sdk</groupId>
          <artifactId>allinpay-syb-sdk-java</artifactId>
          <version>${VERSION}</version>
      </dependency>
      ```
   1. 安装好依赖库保证运行环境没问题，可参考"调用方法"章节的示例代码，请求能正常返回说明运行环境配置成功；
   1. 配置SDK初始化所必须的基础信息(商户号、密钥信息)，看下单是否成功，如能成功，说明商户配置成功，否则请检查商户对接参数配置；
1. 服务端应用对接：安装并部署到您的服务器；
1. 不建议前端应用直接对接依赖SDK，因为这样有可能导致您的商户密钥信息有泄露的风险;

## 五、使用说明
1. 你可以在 [这里](https://prodoc.allinpay.com/doc/2471/) 找到 [Java SDK](/media/attachment/sdk/allinpay-syb-sdk-java.zip) 的源代码、使用说明和最新版本信息。
1. 环境及依赖说明

JDK：Java 1.8+

本 Java SDK 所依赖以下第三方库：
   ```
   <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
       <version>2.10.1</version>
   </dependency>
   
   <dependency>
       <groupId>org.bouncycastle</groupId>
       <artifactId>bcprov-jdk15on</artifactId>
       <version>1.59</version>
   </dependency>
   ```
1. 调用方法
   1. 初始化基础参数；仅需初始化实例一次（单商户模式）
   ```
   AllinpayApi.initialize(MerchantConfig.builder()
                //选送字段，有则送
                .orgId("集团/代理商商户号")
                //选送字段，可实际请求时再指定
                .cusId("商户号")
                //选送字段，可实际请求时再指定
                .appId("应用ID")
                //有条件送，敏感信息加密使用，涉及敏感信息字段加密接口必送
                .sm4Key("SM4密钥")
                //必送字段，枚举详见 SignType 类
                .signType("算法类型")
                //有条件送，商户采用MD5算法进行接口加验签必送
                .md5Key("MD5密钥")
                //有条件送，商户采用RSA1或SM2算法进行接口加验签必送
                .priKeyStr("对应算法所需的商户私钥")
                //有条件送，商户采用RSA1或SM2算法进行接口加验签必送
                .pubKeyStr("对应算法所需的平台公钥")
                //必送字段，枚举详见 Environment 类
                .environment("请求环境"));
   ```
   	 注意：只有配置正确的密钥才可以正常使用SDK，否则会导致调用失败。如涉及对接含敏感信息字段接口必须上送SM4密钥，SDK内部已封装响应加密算法，字段上送明文即可。

2. 开始调用，以 "统一支付请求" 支付为例，向通联支付发起你的第一个请求：
   ```
      /**
        * 统一支付请求
        * <p>使用场景：请求扫码支付的二维码串（支持支付宝、数字人民币、云闪付),公众号JS支付（支付宝，微信，数字人民币，云闪付）,微信小程序支付,微信app支付。
        * </p>
        */
       public static void unitOrderPay(String payType) throws AllinpayException {
           // 初始化请求对象
           UnitOrderPayRequest req = new UnitOrderPayRequest();
           long currentTime = System.currentTimeMillis();
           String timeStr = String.valueOf(currentTime);
           // 交易金额(分)
           req.setTrxAmt("2");
           // 商户交易订单号，和UniReqSn二选一
           req.setReqSn(timeStr);
           // 唯一订单号，和ReqSn二选一
           req.setUniReqSn(timeStr);
           // 交易方式
           req.setPayType(payType);
           // 随机字符串,内置已设值，无特殊需求该值无需设值
           req.setRandomStr(timeStr);
           // 版本号,内置已设值，无特殊需求该值无需设值
           req.setVersion("12");
           // req.setXxx(val)设置所需参数，具体参数可见Request定义或参考线上文档中心
           try {
               HttpConfig config = HttpConfig.build();
               UnitOrderPayResponse response = AllinpayApi.client()
                       .preProcess((httpConfig, readOnlyRequest) -> {
                           System.out.println("请求头:" + JsonUtils.toJson(httpConfig.getHeaders()));
                           System.out.println("请求URL:" + httpConfig.getUrl());
                           System.out.println("请求报文:" + JsonUtils.toJson(readOnlyRequest));
                       })
                       .execObj(config, req);
               System.out.println("响应头:" + JsonUtils.toJson(config.getResponseHeaders()));
               System.out.println("响应报文:" + JsonUtils.toJson(response));
           } catch (AllinpayException e) {
               System.out.println("请求异常:" + e.getMessage());
           }
       }
   ```

## 六、FAQ
1. 如何加验签?

SDK内部已封装加验签功能，只需按说明配置好对应密钥信息即可
1. 敏感字段如何加密?

SDK内部已封装加密功能，只需按说明配置好对应密钥信息即可

1. 多商户模式如何构建支付客户端

"使用说明" 章节已介绍单商户模式如何快速构建支付客户端，对于有多商户模式需求的可采用如下方式构建支付客户端
   ```
     // 支付客户端，开发者需自行维护此实例对象,建议将 allinpayApi 作为单例或全局静态对象，避免重复的实例浪费系统资源
     DelegateAllinpayClient allinpayApi = AllinpayApi
                .builder()
                //（可选配置）->预设商户参数，若请求时指定，则按指定优先
                .injectPayPropConf("集团/代理商商户号", "商户号", "应用ID")
                //（必送配置）证书配置，主要用于报文的加验签，字段的加解密
                .setCertsConfig(
                        CertsConfig.build()
                                // 算法类型 枚举详见 SignType 类
                                .setSignType("算法类型")
                                // （有条件送）如果算法类型是RSA1或SM2必送，注：密钥配置二选一即可，如果商户密钥不以字符串形式存储，可转对象后设置
                                .setPriKey4PKCS8("私钥字符串，PKCS8格式")
                                .setPubKey4PKCS8("公钥字符串，PKCS8格式")
                                .setPrivateKey("私钥对象")
                                .setPublicKey("公钥对象")
                                //（可选配置）商户SM4密钥，涉及敏感信息加密时，这个密钥必送，为了避免涉及字段加密上送的接口请求失败，建议都设置-----
                                .setSm4Key("SM4密钥")
                                //（有条件送），如果算法类型是MD5必送
                                .setMd5Key("MD5密钥"))
                //（必送配置）指定请求环境，枚举详见 Environment 类
                .setEnvironMent("请求环境")
                .build();
   
     // 调用方式，以 “统一支付请求” 为例
     UnitOrderPayRequest req = new UnitOrderPayRequest();
     long currentTime = System.currentTimeMillis();
     String timeStr = String.valueOf(currentTime);
     // 交易金额(分)
     req.setTrxAmt("2");
     // 商户交易订单号，和UniReqSn二选一
     req.setReqSn(timeStr);
     // 唯一订单号，和ReqSn二选一
     req.setUniReqSn(timeStr);
     // 交易方式
     req.setPayType(payType);
     // 随机字符串,内置已设值，无特殊需求该值无需设值
     req.setRandomStr(timeStr);
     // 版本号,内置已设值，无特殊需求该值无需设值
     req.setVersion("12");
     try {
         HttpConfig config = HttpConfig.build();
         UnitOrderPayResponse response = allinpayApi
                 .preProcess((httpConfig, readOnlyRequest) -> {
                     System.out.println("请求头:" + JsonUtils.toJson(httpConfig.getHeaders()));
                     System.out.println("请求URL:" + httpConfig.getUrl());
                     System.out.println("请求报文:" + JsonUtils.toJson(readOnlyRequest));
                 })
                 .execObj(config, req);
         System.out.println("响应头:" + JsonUtils.toJson(config.getResponseHeaders()));
         System.out.println("响应报文:" + JsonUtils.toJson(response));
     } catch (AllinpayException e) {
         System.out.println("请求异常:" + e.getMessage());
     }
   ```

1. 如果我想使用自己系统内部封装的HTTP客户端，如okhttp,HttpClient替代SDK内置HTTP工具，需要如何改造？
   
   可以采用如下方式
   ```
   // 构建支付客户端时调用setCustomHttpClient接口
   DelegateAllinpayClient allinpayApi = AllinpayApi.builder()
      //其它配置项略...
      .setCustomHttpClient(new CustomHttp());
   
   //--------------------------------------分割线----------------------
   
   public class CustomHttp extends AbstractHttp {
      /**
       * 仅支持post请求，响应字符串结果
       * <p>内置已处理加签和验签功能，不用另外实现，专注实现请求过程即可</p>
       * <p>一个请求示例，具体自主实现</p>
       *
       * @param certsConfig 基础证书信息
       * @param httpConfig  基础HTTP请求信息
       * @param request     已构造好的请求参数，MAP结构
       * @return 响应结果字符串
       * @throws AllinpayException 请求异常抛出
       */
      @Override
      public String post(CertsConfig certsConfig, HttpConfig httpConfig, Map<String, String> request) throws AllinpayException {
          // 商户自主实现
          String response = HttpClient.post(request);
          return response;
      }
   }
   
   //--------------------------------------分割线----------------------
   
   //调用方式保持不变
   String response = allinpayApi
              .preProcess((httpConfig, readOnlyRequest) -> {
                  System.out.println("请求头:" + JsonUtils.toJson(httpConfig.getHeaders()));
                  System.out.println("请求URL:" + httpConfig.getUrl());
                  System.out.println("请求报文:" + JsonUtils.toJson(readOnlyRequest));
              })
              .execRaw(config, req);
   ```

1. 执行请求时 execObj和execRaw有什么区别?

区别在于execObj返回的是SDK内部封装的请求结果响应对象；execRaw返回的是原始报文字符串结果。
   <div hidden="">AI抽取结束标记</div>