斗拱开发者论坛

汇付支付斗拱 JAVA 语言 SDKRepository：https://github.com/huifurepo/bspay-java-sdk-parent欢迎使用 斗拱SDK for Java 。斗拱SDK for Java让您不用复杂编程即可访斗拱开放平台开放的各项能力，SDK可以自动帮您满足能力调用过程中所需的证书校验、加签、验签、发送HTTP请求等非功能性要求。 同时，斗拱dg-lightning-sdk提供聚合支付快速接入能力，能大大提升商户接入效率，可以参考dougong-java-lightning-sdk项目，主要包括交易创建、交易查询、交易关闭、交易退款、交易关闭查询、交易退款查询。环境要求斗拱SDK for Java 需要使用JKD 1.8或其以上版本。SDK接入准备提交商户材料完成进件及相关业务配置；登录控台获取/配置密钥，参见《商户密钥操作说明》；准备工作完成后，注意保存如下信息，后续将作为使用SDK的输入。商户的私钥、商户的公钥、汇付的公钥；安装依赖推荐通过Maven来管理项目依赖，您只需在项目的pom.xml文件中声明如下依赖 <dependency> <groupId>com.huifu.bspay.sdk</groupId> <artifactId>dg-java-sdk</artifactId> <version>3.0.2</version> </dependency> <dependency> <groupId>com.huifu.dg.lightning.sdk</groupId> <artifactId>dg-lightning-sdk</artifactId> <version>1.0.3</version> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.70</version> </dependency> <dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> <version>4.5.2</version> </dependency> <dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpmime</artifactId> <version>4.5.2</version> </dependency> <!-- util --> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>3.6</version> </dependency> <!-- okhttp --> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.9.1</version> </dependency> 快速使用安装好依赖库保证运行环境没问题，可直接运行SDK demo，如调用商户详细信息查询正常返回说明运行环境配置成功；改商户配置信息(商户号、私钥)，看下单是否成功，如能成功，说明商户配置成功，否则请检查商户控台配置；部署服务端服务：安装并部署服务端服务到您的服务器，前端应用调用SDK；前端应用对接：前端应用通过网络请求获取到应用服务端从SDK获取的支付信息。在前端页面或者APP内处理后，发起支付。以下这段代码示例向您展示了使用斗拱SDK for Java调用一个API的3个主要步骤：初始化商户参数，完成Client实例并初始化。系统初始化时只需做一次；创建API请求对象并设置Model参数。必填参数用set方法，非必填参数用addExtendInfo()方法设置；发起请求并处理响应或异常。 public static void main(String[] args) throws Exception { // 1. 设置商户参数（全局只需设置一次） doInit(OppsMerchantConfigDemo.getMerchantConfig()); // 2. 组装交易参数 TradePaymentMicropayRequest request = new TradePaymentMicropayRequest(); //请求日期 request.setReqDate(DateTools.getCurrentDateYYYYMMDD()); //请求流水号（保证唯一） request.setReqSeqId(SequenceTools.getReqSeqId32()); //交易金额（单位元） request.setTransAmt("0.01"); //条形码 request.setAuthCode("287606928207260511"); //商品描述 request.setGoodsDesc("测试商品"); //商户id request.setHuifuId("6666000103124174"); // 3.拓展参数 (可选) // 该笔交易的异步通知地址（http/https异步通知地址，必须以virgo://开头） request.addExtendInfo("notify_url", "virgo://http://www.baidu.com"); try { // 3. 发起API调用 Map<String, Object> response = doExecute(request); System.out.println("返回数据:" + JSONObject.toJSONString(response)); } catch (Exception e) { e.printStackTrace(); } } 异步消息说明接口如果有异步返回，请参考斗拱API文档异步消息说明文档SDK文档首页

Dougong Lightning SDK（Java）项目说明Repository：https://github.com/huifurepo/dg-lightning-sdk-java概述Dougong Lightning SDK 以 V4 插件的形式提供极简聚合支付能力，遵循“化繁为简、必参极简 + 可选灵活扩展”的设计风格，通过统一的调用入口与对象化入参模型降低集成成本。主要特性统一入口：通过 Factory 创建客户端，所有能力从一个入口发起。必参极简：主交易字段最小化，低频参数走扩展注入。可插拔扩展：optional(key, value) 注入场景参数，保持模型稳定。统一管道：入参归一、扩展合并、序列化、路由与调用一体化。多场景覆盖：下单、查询、关单、退款、退款查询。包结构简述factory：统一入口与客户端创建（Factory）。biz.client：业务客户端与链式扩展（CommonPayClient、BasePayClient）。biz.net：网关请求、签名与路由（BasePayRequest）。models：对象化入参/响应与领域对象（如 TradePaymentCreateRequest、分账对象）。utils：基础工具与配置（BasePay、DateTools、SequenceTools 等）。安装与引入在上层业务模块的 pom.xml 中引入：<dependency> <groupId>com.huifu.dg.lightning.sdk</groupId> <artifactId>dg-lightning-sdk</artifactId> <version>1.0.3</version> </dependency> 场景快速冒烟目标：零门槛验证“统一入口 + 极简扩展”是否接通。示例目录：查看 dougong-java-sdk项目的bspay-java-sdk-sample 项目操作步骤：在示例目录选择一个交易类型示例类（如 JSAPI/正扫/付款码）。设置主交易字段：req_date、req_seq_id、huifu_id、goods_desc、trans_amt、trade_type。注入通道扩展：将场景参数对象序列化为 JSON，使用 optional("method_expand", json) 注入；叠加收单能力：如需贴息/增值等，序列化为 JSON，使用 optional("tx_metadata", json) 注入。运行示例类的 main 或测试方法，观察返回的交易号/二维码/支付参数等核心结果。快速开始// 1. 初始化商户配置（建议从配置中心加载 MerConfig 后调用 BasePay.initWithMerConfig） BasePay.initWithMerConfig(merConfig); // 2. 组装必填入参（以聚合下单为例） TradePaymentCreateRequest req = new TradePaymentCreateRequest(); req.setReqDate(DateTools.getCurrentDateYYYYMMDD()); req.setReqSeqId(SequenceTools.getReqSeqId32()); req.setHuifuId("6666xxxxxxxxxxx"); req.setGoodsDesc("商品描述"); req.setTransAmt("0.01"); req.setTradeType("A_JSAPI"); // 3. 通过工厂获取客户端并发起调用 Map<String, Object> resp = Factory.Payment.Common() .optional("notify_url", "https://your.notify/url") .create(req); 可选参数扩展使用链式的 optional(key, value) 在客户端注入低频参数，这些参数将与请求体合并并覆盖同名字段。下单统一入口与扩展模型单一入口：所有支付下单统一通过 CommonPayClient#create 发起交易抽象：用 trade_type 标识具体支付场景；用 method_expand 承载该场景的专有参数，二者组合即为“交易对象”的扩展模型。收敛策略：新增或变更任意交易场景时，仅需定义场景参数对象 → 序列化为 JSON → 注入 method_expand，无需新增接口或客户端方法。推荐用法：保持必参极简，扩展参数一律通过 optional("method_expand", json) 注入；若无扩展，传 "{}" 即可。调用示例：req.setTradeType("T_JSAPI"); String json = JSON.toJSONString(wxData); Map<String, Object> resp = Factory.Payment.Common() .optional("method_expand", json) .create(req); 交易设计理念意向订单（主交易字段）：用统一的主字段表达订单意向与基础要素，如日期、流水号、商户、金额、商品等，保持稳定不随渠道变化。通道信息（trade_type + method_expand）：以 trade_type 选择支付通道/场景，以 method_expand 承载该通道的专有参数，二者组合定义“如何支付”。新增渠道能力只需新增专有参数对象并通过 method_expand 注入，无需改动统一入口。收单附加能力（tx_metadata）：用于承载收单侧扩展能力，如贴息、分期、优惠分账、增值等，以 JSON 字符串注入即可。三层划分：将一次交易抽象为“意向订单（主字段）+ 通道（trade_type+method_expand）+ 收单附加能力（tx_metadata）”。该划分确保主交易模型稳定、通道能力可插拔、收单扩展可累加，统一入口下自然演进。统一请求管道（简述）入参归一：将请求对象规范化为键值对。扩展合并：合并扩展参数，客户端注入覆盖同名字段。特殊序列化：对象型特殊字段统一序列化为 JSON 字符串。路径解析与调用：将功能码解析为网关路径，完成 HTTP 调用并返回统一结果。常用接口示例支付下单：CommonPayClient#create（TradePaymentCreateRequest）支付查询：CommonPayClient#query关单：CommonPayClient#close退款：CommonPayClient#refund退款查询：CommonPayClient#refundQuery开箱即用与场景示例项目定位：本包为 V4 极简插件，示例与运行入口位于主 SDK 项目。示例目录：bspay-java-sdk-parent/bspay-java-sdk-sample/src/main/java/com/huifu/bspay/sdk/demo/v4使用方式：在主 SDK 示例目录中选择对应交易类型的示例类，按需修改基础入参与扩展参数（trade_type + method_expand / tx_metadata），直接运行。配置说明：主 SDK 通过配置中心加载环境与密钥信息；如运行异常，请在主 SDK 项目中调整环境与商户配置。配置说明通过 BasePay.initWithMerConfig(MerConfig) 或 BasePay.initWithMerConfigs(Map<String, MerConfig>) 完成多商户配置加载（dg-lightning-sdk/src/main/java/com/huifu/dg/lightning/utils/BasePay.java:57-71）。调用时使用默认商户配置，或在请求方法中指定 merchantKey 选择商户配置（BasePayRequest 的对应重载）。BasePay.prodMode 控制目标环境域名（生产/联测/内部），统一封装于 BasePayRequest 调用路径解析。异常与错误许可与版本版本：1.0.3许可证：Apache-2.0（详见根 POM）