版本：Next

PAX-串口数据交互文档-1.1.0

版本号	编辑者	更新时间	更新内容
V1.0.0	陈浩	2024/10/14	创建
V1.1.0	房杨平	2025/07/22	数据使用JSON通信,废弃base参数模块, 适用收单应用1.2.4版本, 已过期, 请升级到最新版本

功能描述

串口初始化：设置串口参数并打开串口与设备建立连接。
数据接收：通过回调接口接收从设备发送的数据。
数据发送：向外部设备发送数据。

SDK下载

SDK下载地址: sxf-20250725-serial-port-v1.1.0.aar
源码下载地址: serial-sdk-demo-1.1.0.zip

接口介绍

注意：这里所有的接口参数都以JSON的格式,所有的接口请求和响应都应该包含公共参数信息。

公共请求参数信息

参数名	类型	是否必填	描述
`api`	`String`	是	接口
`requestId`	`String`	否	调用方唯一请求流水号

公共响应参数信息

参数名	类型	是否必填	描述
`code`	`String`	是	业务响应码，定义业务处理结果状态（见下方响应码说明）
`msg`	`String`	是	业务响应描述信息，用于说明响应码对应的具体结果
`data`	`Object`	是	数据对象
├─ `requestId`	`String`	否	原样返回请求中的流水号，用于请求-响应匹配校验
├─ `api`	`String`	是	接口
├─ `sn`	`String`	是	终端SN

公共响应结构

{
  "code": "00",
  "msg": "SUCCESS",
  "data": {
    "requestId": "971dda25971dda25971dda25",
    "sn": "247KCASL1947",
    "api": "/sale",
    "..."
  }
}

响应码定义表

常量名	值	类型	说明
`REQUEST`	`"04"`	String	表示请求已发出（待处理状态）
`CONFIRM`	`"03"`	String	请求确认收到（已接收未处理）
`PROCESSING`	`"02"`	String	请求正在处理中（异步处理）
`FAIL`	`"01"`	String	受理异常（业务失败）
`SUCCESS`	`"00"`	String	正常受理（业务成功）

使用说明

初始化串口

serialService = SerialSDKService.getInstance(context);
serialService.setListener(this);
serialService.create("/dev/ttyS2", 9600);
serialService.open();

示例代码

以下是一个完整的示例代码，展示如何使用此 SDK：

public class MainActivity extends AppCompatActivity implements SerialListener  {
    private SerialSDKService serialService;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

       serialService = SerialSDKService.getInstance(context);
       serialService.setListener(this);
       serialService.create("/dev/ttyS2", 9600);
       serialService.open();

       try {
           JSONObject jsonObject = new JSONObject();
           jsonObject.put("api", "/sale");
           jsonObject.put("requestId", "requestId");
           jsonObject.put("orderAmount", "1.00");
           jsonObject.put("merchantSerialNo", UUID.randomUUID());
           jsonObject.put("orderTitle", "Sale");
           JSONArray detailsArray = new JSONArray();
           detailsArray.put("coke * 2");
           detailsArray.put("chip * 5");
           jsonObject.put("orderDetails", detailsArray);
           String jsonString = jsonObject.toString();
           serialService.sendText(jsonString);
        } catch (JSONException e) {
            throw new RuntimeException(e);
          }
    }

    @Override
    public void onDataReceived(String jsonString) {
        try {
            Log.i(TAG, "onDataReceived result: " + new JSONObject(jsonString));
            JSONObject jsonObject = new JSONObject(jsonString);
            String code = jsonObject.optString("code");
            String msg = jsonObject.optString("msg");
            if(code.equals("00")) {
                JSONObject data = jsonObject.optJSONObject("data");
                if (data != null) {
                    String api = data.optString("api");
                    String requestId = data.optString("requestId");
                    String sn = data.optString("sn");

                    Log.d("JSON", "api = " + api);

                    if (api.equals("/sale") && requestId.equals("requestId")) {
                        Log.i(TAG, "onDataReceived: Processing /sale return data");
                    }
                }
            }else {
                Log.e(TAG, "onDataReceived: " + msg );
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onError(int errorCode, String errorMessage) {
        Log.i(TAG, "onError: " + errorCode + " errorMessage:" + errorMessage);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        serialService.close(); 
    }
}

接口列表

签到

接口：`/sign`

请求参数

参数名	类型	是否必填	描述
`api`	`String`	是	接口

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/sign");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/sign",
}

响应参数

参数名	类型	描述
`signStatus`	`String`	签到状态 `YES` `NO`
`merchantNo`	`String`	商户号
`defaultAmount`	`String`	预授权金额
`showCardSwipeButton`	`String`	是否显示刷卡按钮 `SHOW` `HIDE`

示例

{
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/sign",
    "sn":"3080004570",
    "signStatus":"YES",
    "merchantNo":"4276000064",
    "defaultAmount":"45.00",
    "showButton":"SHOW",
    }
}

查询签到信息

接口：`/query/device/status`

请求参数

参数名	类型	是否必填	描述
`api`	`String`	是	接口

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/query/device/status");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/query/device/status",
}

响应参数

参数名	类型	描述
`signStatus`	`String`	签到状态 `YES` `NO`
`merchantNo`	`String`	商户号
`defaultAmount`	`String`	预授权金额
`showCardSwipeButton`	`String`	是否显示刷卡按钮 `SHOW` `HIDE`

示例

{
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/query/device/status",
    "sn":"3080004570",
    "signStatus":"YES",
    "merchantNo":"4276000064",
    "defaultAmount":"45.00",
    "showButton":"SHOW",
    }
}

消费

接口: `/sale`

请求参数说明

参数名	类型	是否必填	描述
`api`	`String`	是	接口
`merchantSerialNo`	`String`	是	商户交易流水号（需保证全局唯一性）
`orderAmount`	`String`	是	订单金额（最小值为0.01，单位：元，两位小数）
`orderTitle`	`String`	否	订单标题
`orderDetails`	Array	否	订单内容 `["可乐(2)", "薯片(3)"]`
`externalAdditionalData`	`String`	否	附加信息

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/sale");
jsonObject.put("orderAmount", amount);
jsonObject.put("merchantSerialNo", UUID.randomUUID());
jsonObject.put("orderTitle", "Sale");
JSONArray detailsArray = new JSONArray();
detailsArray.put("coke * 2");
detailsArray.put("chip * 5");
jsonObject.put("orderDetails", detailsArray);
jsonObject.put("externalAdditionalData", "external data");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/sale",
  "orderAmount":"1.00",
  "merchantSerialNo":"5b58028a-7678-4f70-8a32-de0669e0d476",
  "orderTitle":"Sale",
  "orderDetails":["coke * 2","chip * 5"],
  "externalAdditionalData":"external data",
}

响应参数

字段名	类型	字段名称说明
`orderNo`	String	平台订单号
`merchantSerialNo`	String	订单号
`transactionStatus`	String	订单状态
`transactionNo`	String	交易号
`orderAmount`	String	金额
`currency`	String	币种
`transactionTime`	String	交易时间

示例

 {
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/sale",
    "sn":"3080004570",
    "merchantSerialNo":"5b58028a-7678-4f70-8a32-de0669e0d476",
    "transactionNo":"TK552EAAA85800000844363619614720",
    "orderNo":"10220250722000011228",
    "transactionStatus":"11",
    "currency":"EUR",
    "orderAmount":"1.00",
    "transactionTime":"2025-07-22T12:25:46.000+00:00"
    }
  }

预授权

接口: `/auth`

请求参数说明

参数名	类型	是否必填	描述
`api`	`String`	是	接口
`merchantSerialNo`	`String`	是	商户交易流水号（需保证全局唯一性）
`orderAmount`	`String`	是	订单金额（最小值为0.01，单位：元，两位小数）
`orderTitle`	`String`	否	订单标题
`orderDetails`	Array	否	订单内容 `["可乐(2)", "薯片(3)"]`
`externalAdditionalData`	`String`	否	附加信息

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/auth");
jsonObject.put("orderAmount", amount);
jsonObject.put("merchantSerialNo", UUID.randomUUID());
jsonObject.put("orderTitle", "Auth");
JSONArray detailsArray = new JSONArray();
detailsArray.put("coke * 2");
detailsArray.put("chip * 5");
jsonObject.put("orderDetails", detailsArray);
jsonObject.put("externalAdditionalData", "external data");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/auth",
  "orderAmount":"1.00",
  "merchantSerialNo":"5b58028a-7678-4f70-8a32-de0669e0d476",
  "orderTitle":"Auth",
  "orderDetails":["coke * 2","chip * 5"],
  "externalAdditionalData":"external data",
}

响应参数

字段名	类型	字段名称说明
`orderNo`	String	平台订单号
`merchantSerialNo`	String	订单号
`transactionStatus`	String	订单状态
`transactionNo`	String	交易号
`orderAmount`	String	金额
`currency`	String	币种
`transactionTime`	String	交易时间

示例

 {
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/auth",
    "sn":"3080004570",
    "merchantSerialNo":"5b58028a-7678-4f70-8a32-de0669e0d476",
    "transactionNo":"TK552EAAA85800000844363619614720",
    "orderNo":"10220250722000011228",
    "transactionStatus":"11",
    "currency":"EUR",
    "orderAmount":"1.00",
    "transactionTime":"2025-07-22T12:25:46.000+00:00"
    }
  }

预授权完成

接口: `/auth/capture`

请求参数说明

参数名	类型	是否必填	描述
`api`	`String`	是	接口
`merchantSerialNo`	`String`	是	原预授权交易流水号
`orderAmount`	`String`	是	订单金额（最小值为0.01，单位：元，两位小数）

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/auth/capture");
jsonObject.put("orderAmount", amount);
jsonObject.put("merchantSerialNo", "merchantSerialNo");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/auth/capture",
  "orderAmount":"1.00",
  "merchantSerialNo":"merchantSerialNo"
}

响应参数

字段名	类型	字段名称说明
`orderNo`	String	平台订单号
`merchantSerialNo`	String	订单号
`transactionStatus`	String	订单状态
`transactionNo`	String	交易号
`orderAmount`	String	金额
`currency`	String	币种
`transactionTime`	String	交易时间

示例

 {
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/auth/capture",
    "sn":"3080004570",
    "merchantSerialNo":"5b58028a-7678-4f70-8a32-de0669e0d476",
    "transactionNo":"TK552EAAA85800000844363619614720",
    "orderNo":"10220250722000011228",
    "transactionStatus":"11",
    "currency":"EUR",
    "orderAmount":"1.00",
    "transactionTime":"2025-07-22T12:25:46.000+00:00"
    }
  }

预授权撤销

接口: `/auth/revoke`

请求参数说明

参数名	类型	是否必填	描述
`api`	`String`	是	接口
`merchantSerialNo`	`String`	是	原预授权交易流水号

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/auth/revoke");
jsonObject.put("merchantSerialNo", "merchantSerialNo");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/auth/capture",
  "merchantSerialNo":"merchantSerialNo"
}

响应参数

字段名	类型	字段名称说明
`orderNo`	String	平台订单号
`merchantSerialNo`	String	订单号
`transactionStatus`	String	订单状态
`transactionNo`	String	交易号
`orderAmount`	String	金额
`currency`	String	币种
`transactionTime`	String	交易时间

示例

 {
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/auth/revoke",
    "sn":"3080004570",
    "merchantSerialNo":"5b58028a-7678-4f70-8a32-de0669e0d476",
    "transactionNo":"TK552EAAA85800000844363619614720",
    "orderNo":"10220250722000011228",
    "transactionStatus":"11",
    "currency":"EUR",
    "orderAmount":"1.00",
    "transactionTime":"2025-07-22T12:25:46.000+00:00"
    }
  }

预授权追加

接口: `/auth/incremental`

请求参数说明

参数名	类型	是否必填	描述
`api`	`String`	是	接口
`merchantSerialNo`	`String`	是	原预授权交易流水号
`orderAmount`	`String`	是	订单金额（最小值为0.01，单位：元，两位小数）

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/auth/incremental");
jsonObject.put("orderAmount", amount);
jsonObject.put("merchantSerialNo", "merchantSerialNo");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/auth/incremental",
  "orderAmount":"1.00",
  "merchantSerialNo":"merchantSerialNo"
}

响应参数

字段名	类型	字段名称说明
`orderNo`	String	平台订单号
`merchantSerialNo`	String	订单号
`transactionStatus`	String	订单状态
`transactionNo`	String	交易号
`orderAmount`	String	金额
`currency`	String	币种
`transactionTime`	String	交易时间

示例

 {
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/auth/incremental",
    "sn":"3080004570",
    "merchantSerialNo":"5b58028a-7678-4f70-8a32-de0669e0d476",
    "transactionNo":"TK552EAAA85800000844363619614720",
    "orderNo":"10220250722000011228",
    "transactionStatus":"11",
    "currency":"EUR",
    "orderAmount":"1.00",
    "transactionTime":"2025-07-22T12:25:46.000+00:00"
    }
  }

设置营业

接口：`/open/business`

请求参数

参数名	类型	是否必填	描述
`api`	`String`	是	接口

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/open/business");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/open/business",
}

响应参数

参数名	类型	描述
`businessStatus`	`String`	营业状态 `OPEN` `CLOSE`

示例

{
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/open/business",
    "sn":"3080004570",
    "businessStatus":"1OPEN",
    }
}

设置停业

接口：`/stop/business`

请求参数

参数名	类型	是否必填	描述
`api`	`String`	是	接口

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/stop/business");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/stop/business",
}

响应参数

参数名	类型	描述
`businessStatus`	`String`	营业状态 `OPEN` `CLOSE`

示例

{
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/stop/business",
    "sn":"3080004570",
    "businessStatus":"CLOSE",
    }
}

查询营业状态

接口：`/query/business/status`

请求参数

参数名	类型	是否必填	描述
`api`	`String`	是	接口

JAVA代码

JSONObject jsonObject = new JSONObject();
jsonObject.put("api", "/query/business/status");
serialService.sendText(jsonObject.toString());

JSON

{
  "api":"/query/business/status",
}

响应参数

参数名	类型	描述
`businessStatus`	`String`	营业状态 `OPEN` `CLOSE`

示例

{
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/query/business/status",
    "sn":"3080004570",
    "businessStatus":"OPEN",
    }
}

功能描述​

SDK下载​

接口介绍​

公共请求参数信息​

公共响应参数信息​

公共响应结构​

响应码定义表​

使用说明​

初始化串口​

示例代码​

接口列表​

签到​

接口：/sign​

请求参数​

响应参数​

查询签到信息​

接口：/query/device/status​

请求参数​

响应参数​

消费​

接口: /sale​

请求参数说明​

响应参数​

预授权​

接口: /auth​

请求参数说明​

响应参数​

预授权完成​

接口: /auth/capture​

请求参数说明​

响应参数​

预授权撤销​

接口: /auth/revoke​

请求参数说明​

响应参数​

预授权追加​

接口: /auth/incremental​

请求参数说明​

响应参数​

设置营业​

接口：/open/business​

请求参数​

响应参数​

设置停业​

接口：/stop/business​

请求参数​

响应参数​

查询营业状态​

接口：/query/business/status​

请求参数​

响应参数​

功能描述

SDK下载

接口介绍

公共请求参数信息

公共响应参数信息

公共响应结构

响应码定义表

使用说明

初始化串口

示例代码

接口列表

签到

接口：`/sign`

请求参数

响应参数

查询签到信息

接口：`/query/device/status`

请求参数

响应参数

消费

接口: `/sale`

请求参数说明

响应参数

预授权

接口: `/auth`

请求参数说明

响应参数

预授权完成

接口: `/auth/capture`

请求参数说明

响应参数

预授权撤销

接口: `/auth/revoke`

请求参数说明

响应参数

预授权追加

接口: `/auth/incremental`

请求参数说明

响应参数

设置营业

接口：`/open/business`

请求参数

响应参数

设置停业

接口：`/stop/business`

请求参数

响应参数

查询营业状态

接口：`/query/business/status`

请求参数

响应参数