Register-SDK for JAVA

1. 入门

1.1 前提条件

• JDK 1.8及以上版本的开发环境。
• 运行Windows、MacOS或Linux操作系统的台式计算机或设备。

1.2 安装和配置

1. 应用程序安装和设置，请参阅 USB模式集成 和 WLAN/LAN模式集成。

2. 下载jar包并将其添加到您的项目中，请参阅GitHub源代码。

源代码和库	WLAN模式	USB模式
https://github.com/codepay-us/codepay-register-sdk-java	Windows/Linux/MacOS	Windows
https://github.com/codepay-us/codepay-register-cross-terminal-integration-demo-java

3. Maven依赖项
   备注

   SDK依赖于一些开源的第三方jar。如果这些jar没有集成到您的项目中，您将需要手动向项目添加依赖项。

<!-- Mandatory -->
<!-- jSerialComm -->
<dependency>
    <groupId>com.fazecast</groupId>
    <artifactId>jSerialComm</artifactId>
    <version>[2.0.0,3.0.0)</version>
</dependency>
<!-- WebSocket -->
<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.4</version>
</dependency>
<!-- fastjson2 -->
<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.26</version>
</dependency>
<!-- hutool -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.21</version>
</dependency>
<!-- slf4j-api -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.9</version>
</dependency>
<!-- jmdns -->
<dependency>
  <groupId>org.jmdns</groupId>
  <artifactId>jmdns</artifactId>
  <version>3.5.8</version>
</dependency>

<!-- non-mandatory -->
<!-- logback -->
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.3.11</version>
</dependency>
<!-- junit -->
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.8.1</version>
    <scope>test</scope>
</dependency>

2. 函数列表

2.1 设备发现和配对

备注

只有WLAN连接模式需要先配对，USB连接模式不需要配对。

2.1.1 启动/停止设备发现服务

只有在设备发现服务启动时，终端才能发现您的POS应用程序

• 在完成配对操作后，终端和POS应用程序将记录彼此的网络信息
• 当需要配对和连接到网络时，需要启用设备发现服务

import com.codepay.register.sdk.device.ECRHubDiscoveryService;
import com.codepay.register.sdk.device.ECRHubWebSocketDiscoveryService;

ECRHubDiscoveryService service = ECRHubWebSocketDiscoveryService.getInstance();
//start device discover service
service.start();

//stop device discover service
service.stop();

2.1.2 获取配对终端的列表

• 使用POS应用程序推送订单时，您可以从配对设备列表中选择一个设备来推送订单；
• 当POS应用程序需要显示配对的POS终端时，此功能可用于获得配对设备的列表以供显示。

import com.codepay.register.sdk.device.ECRHubDevice;
import com.codepay.register.sdk.device.ECRHubDiscoveryService;
import com.codepay.register.sdk.device.ECRHubWebSocketDiscoveryService;

ECRHubDiscoveryService service = ECRHubWebSocketDiscoveryService.getInstance();

List<ECRHubDevice> pairedDeviceList = service.getPairedDeviceList();
for (ECRHubDevice ecrHubDevice : pairedDeviceList) {
    System.out.println("terminal_sn:" + ecrHubDevice.getTerminal_sn());
    System.out.println("ws_address:" + ecrHubDevice.getWs_address());
    
    // Create ECRHubClient instance object based on ws_address
    // ECRHubClient client = ECRHubClientFactory.create(ecrHubDevice.getWs_address());
}

2.1.3 移除配对的端子

当POS终端不再使用时，可以手动将其从POS应用程序的配对列表中删除。

import com.codepay.register.sdk.device.ECRHubDevice;
import com.codepay.register.sdk.device.ECRHubDiscoveryService;
import com.codepay.register.sdk.device.ECRHubWebSocketDiscoveryService;

ECRHubDiscoveryService service = ECRHubWebSocketDiscoveryService.getInstance();
List<ECRHubDevice> pairedDeviceList = service.getPairedDeviceList();

// Select the device to be removed for removal
ECRHubDevice device = pairedDeviceList.get(0);
service.unpair(device);

2.2 连接

选择一个配对的终端来启动网络连接，一旦建立了连接，就可以发送交易指令。

2.2.1 调用过程

2.2.2 创建客户端实例

WLAN连接模式

当POS应用程序使用WLAN连接到POS终端时，请使用以下方法创建客户端

import com.codepay.register.sdk.ECRHubClient;
import com.codepay.register.sdk.ECRHubConfig;
import com.codepay.register.sdk.ECRHubClientFactory;

// Create a client instance
ECRHubConfig config = new ECRHubConfig();
// Setting socket timeout
config.getSocketConfig().setConnTimeout(10 * 1000);
config.getSocketConfig().setWriteTimeout(10 * 1000);
config.getSocketConfig().setReadTimeout(120 * 1000);

// Please replace "xxxxxx" with the real host and port
ECRHubClient client = ECRHubClientFactory.create("ws://xxxxxx", config);

USB连接模式

当POS应用程序使用USB电缆连接到POS终端时，请使用以下方法创建客户端

import com.codepay.register.sdk.ECRHubClient;
import com.codepay.register.sdk.ECRHubConfig;
import com.codepay.register.sdk.ECRHubClientFactory;

// Create a client instance By Serial port
ECRHubConfig config = new ECRHubConfig();
// Setting Serial Port timeout
config.getSerialPortConfig().setConnTimeout(10 * 1000);
config.getSerialPortConfig().setWriteTimeout(10 * 1000);
config.getSerialPortConfig().setReadTimeout(120 * 1000);

// Method 1: Specify the serial port name. Please replace "xxxxxx" with the real serial port name. For example: COM6
// ECRHubClient client = ECRHubClientFactory.create("sp://xxxxxx", config);

// Method 2: Do not specify the serial port name. The SDK will automatically find available serial port
ECRHubClient client = ECRHubClientFactory.create("sp://", config);

2.2.3 连接

在POS应用程序和POS终端之间建立连接。

// Connecting to the POS Terminal
client.connect();

2.2.4 断开连接

断开POS应用程序与POS终端的连接。

// This will try disconnect from POS Terminal
client.disconnect();

2.3 交易

2.3.1 消费

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.SaleRequest;
import com.codepay.register.sdk.model.response.SaleResponse;
import com.codepay.register.sdk.enums.EPayScenario;

// Build sale request
SaleRequest request = new SaleRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setMerchant_order_no("O123456789");
request.setOrder_amount("1");
request.setPay_scenario(EPayScenario.SWIPE_CARD.getVal());

// Setting read timeout,the timeout set here is valid for this request
ECRHubConfig requestConfig = new ECRHubConfig();
requestConfig.getSerialPortConfig().setReadTimeout(2 * 60 * 1000);
request.setConfig(requestConfig);
        
// Execute sale request
System.out.println("Sale Request:" + request);
SaleResponse response = client.execute(request);
System.out.println("Sale Response:" + response);

2.3.2 返现

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.SaleWithCashbackRequest;
import com.codepay.register.sdk.model.response.SaleWithCashbackResponse;
import com.codepay.register.sdk.enums.EPayScenario;

// Build sale with cashback request
SaleWithCashbackRequest request = new SaleWithCashbackRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setMerchant_order_no("O123456789");
request.setOrder_amount("50");
request.setCashback_amount("20");
request.setPay_scenario(EPayScenario.SWIPE_CARD.getVal());

// Setting read timeout,the timeout set here is valid for this request
ECRHubConfig requestConfig = new ECRHubConfig();
requestConfig.getSerialPortConfig().setReadTimeout(2 * 60 * 1000);
request.setConfig(requestConfig);
        
// Execute sale with cashback request
System.out.println("SaleWithCashback Request:" + request);
SaleWithCashbackResponse response = client.execute(request);
System.out.println("SaleWithCashback Response:" + response);

2.3.3 预授权

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.AuthRequest;
import com.codepay.register.sdk.model.response.AuthResponse;
import com.codepay.register.sdk.enums.EPayScenario;

// Build authorization request
AuthRequest request = new AuthRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setMerchant_order_no("O123456789");
request.setOrder_amount("1");
request.setPay_scenario(EPayScenario.SWIPE_CARD.getVal());
        
// Execute authorization request
System.out.println("Authorization Request:" + request);
AuthResponse response = client.execute(request);
System.out.println("Authorization Response:" + response);

2.3.4 预授权完成

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.CompletionRequest;
import com.codepay.register.sdk.model.response.CompletionResponse;

// Build completion request
CompletionRequest request = new CompletionRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setOrig_merchant_order_no("O1695032342508");// The merchant order number of the original Authorization order
request.setMerchant_order_no("O123456789");
request.setOrder_amount("1");
        
// Execute completion request
System.out.println("Completion Request:" + request);
CompletionResponse response = client.execute(request);
System.out.println("Completion Response:" + response);

2.3.5 撤销

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.VoidRequest;
import com.codepay.register.sdk.model.response.VoidResponse;

// Build void request
VoidRequest request = new VoidRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setMerchant_order_no("O123456789");
        
// Execute void request
System.out.println("Void Request:" + request);
VoidResponse response = client.execute(request);
System.out.println("Void Response:" + response);

2.3.6 退款

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.RefundRequest;
import com.codepay.register.sdk.model.response.RefundResponse;

// Build refund request
RefundRequest request = new RefundRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setOrig_merchant_order_no("O1695032342508");// The merchant order number of the original order
request.setMerchant_order_no("O123456789");
request.setOrder_amount("1");
        
// Execute refund request
System.out.println("Refund Request:" + request);
RefundResponse response = client.execute(request);
System.out.println("Refund Response:" + response);

2.3.7 查询

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.QueryRequest;
import com.codepay.register.sdk.model.response.QueryResponse;

// Build query request
QueryRequest request = new QueryRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setMerchant_order_no("O123456789");

// Execute query request
System.out.println("Query Request:" + request);
QueryResponse response = client.execute(request);
System.out.println("Query Response:" + response);

2.3.8 关闭

1. 请求/响应参数
2. 示例:

import com.codepay.register.sdk.model.request.CloseRequest;
import com.codepay.register.sdk.model.response.CloseResponse;

// Build close request
CloseRequest request = new CloseRequest();
request.setApp_id("Your payment appid"); // Setting your payment application ID
request.setMerchant_order_no("O123456789");

// Execute close request
System.out.println("Close Request:" + request);
CloseResponse response = client.execute(request);
System.out.println("Close Response:" + response);