Copyright Notice

Copyright © 2021 PAX Computer Technology (Shenzhen) Co., Ltd. All Rights Reserved.

The Programs (which include both the software and documentation) contain proprietary information. Such programs are provided by copyright holders under the limited license and are also protected by copyright, patent, and other intellectual and industrial property laws. Please respect the ownership rights of us and others. In no event shall you copy, modify, distribute and disassemble the software and/or documentation, except to the extent required to obtain interoperability with other independently created software or as specified by law.

The programs are provided "as is," and copyright holders make no representations or warranties, express or implied, including, but not limited to, warranties of merchantability, fitness for a particular purpose, non-infringement, or title; that the contents of the document are suitable for any purpose; nor that the implementation of such contents will not infringe any third party patents, copyrights, trademarks or other rights.

Copyright holders will not be liable for any direct, indirect, special or consequential damages arising out of any use of the document or the performance or implementation of the contents thereof.

The name and trademarks of copyright holders cannot be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

The information contained in this Copyright Notice is subject to change without notice. If you find any problems in this Copyright Notice, please report them to us in writing. This Copyright Notice is not warranted to be error-free.

# 修订历史记录

时间 | 版本 | 作者 | 内容
--- | --- | --- | ---
2025/03/06 | V1.02.03 | Ben.J | 1. 添加110133 PIN KEY MISSING和110134 PIN KEY AND P2PE KEY MISSING到响应码和响应消息。 2. 修改hostReferenceNumber的属性为ans…64。 3. 更新了Ping命令中timeout的描述。 4. 添加detectCardTimeout到GConfigurationNames和SConfigurationNames中。 5. 添加amountInformation到GetTransactionInfo命令的response中。
2024/09/09 | V1.02.02 | Ben.J | 1. 添加amountInformation到TransactionStartRsp、TransactionIncrementalRsp和TransactionCompletionRsp。 2. 添加enableCardUniqueIdentifier到TransactionStartReq、GetCardStatusReq和GetCardInfoReq。 3. 添加110225 NEED READ CARD FIRST和110300 PARTIALLY APPROVED到响应码和响应消息。 4. 添加cardUniqueIdentifier到AccountRsp。
2024/04/30 | V1.02.01 | Ben.J | 1. 添加ipAddress、subnetMask、defaultGateway、dnsServer和backgroundMode到SConfigurationNames类。 2. 添加110131 IP CONFIGURATION DISABLED IN DHCP和110132 IP CONFIGURATION PARAMETER ERROR到响应码和响应消息。 3. 添加transactionAmount到GetCardInfoReq类。 4. 添加appVersion、appUpdateTimeStamp和ipAddress到GetTerminalInfoRsp类。
2023/11/21 | V1.02.00 | Ben.J | 1. 添加TransactionIncremental命令。 2. 添加hostGateway和accountInformation到TransactionStart的request。 3. 添加hostInformation到TransactionStart的response。 4. 添加110002 EXP DATE INVALID，110002 TOKEN REQUEST FLAG INVALID，110222 CARD EXPIRE DATE MISSING和110223 SERVICE BUSY到响应码和响应消息。
2023/10/18 | V1.01.09 | Ben.J | 1. 添加displayMode到GConfigurationNames和SConfigurationNames。 2. 添加110224 PARAMETERS FILE CORRUPTION到响应码和响应消息。
2023/07/24 | V1.01.08 | Ben.J | 1. 添加110221 AUTOMATIC REBOOT COUNTDOWN到响应码和响应消息。
2023/07/04 | V1.01.07 | Ben.J | 1. 更新了一些描述. 2. 新增AccountRsp到TransactionStart/GetCardStatus/GetCardInfo的response中. 3. 新增CardType到AccountRsp中。
2023/05/25 | V1.01.06 | Ben.J | 1. 增加tapPromptMsgLine1/tapPromptMsgLine2/cardReadSuccessMsg/tapImageName到GConfigurationNames和SConfigurationNames中。 2. 修改registerReferenceNumber的属性为ans…32。 3. 修改STX相关描述。
2023/04/12 | V1.01.05 | Ben.J | 1. 增加InputText命令。 2. 增加InputText相关响应码和响应消息。
2023/02/20 | V1.01.04 | Ben.J | 1. 将一些属性的是否必需修改成O或C。 2. 添加responseMessage的描述链接。 3. 修复一些语法错误。 4. 增加新机型IM15到Terminal。
2023/01/30 | V1.01.03 | Ben.J | 1. 添加cardType到GetCardStatus Response中。 2. 修改GetCardStatus Response中的account的描述。
2023/01/09 | V1.01.02 | Ben.J | 1. 添加currencyCode于GConfigurationNames中。
2022/09/16 | V1.01.01 | Ben.J | 1. 修复GConfigurationNames没有超链接的问题。 2. 重命名“通信头”为“报文头”。 3. 增加GetCardInfo命令。
2022/09/02 | V1.01.00 | Jerry.Z | 1. 第一个中文版本。

# 序言

## 目的

本文档致力于提供自助服务终端以及PAX终端之间的通信接口定义，本文档将包含以下主题。

- 序言
- 概述
- 通信协议
- 通信场景
- 一般交易流程
- 命令数据属性
- 命令定义
- 命令对象定义
- 常量值定义
- 附录

## 预期读者

本文档的预期读者如下：

- 自助服务终端设备应用开发人员
- PAX 终端应用开发人员

## 文档约定

- RFU：预留给未来使用。

# 概述

## 简介

PAX为自助服务终端和支付终端进行通信提供了一个简单的集成方案，操作员可以通过使用交易命令来避免数据和通信过程中的监控。目前有四种类型的命令Admin，Transaction，Batch，Device，Report。 其中Admin系列负责终端管理，Transaction系列负责交易处理， Batch负责和后台的清结算，Device负责操作硬件相关功能，Report负责报告交易的执行结果。

### 通信方式

自助服务终端可以通过UART/USB 或者 TCP/SSL 和支付终端进行通信。

- UART/USB
  - 对于UART，自助服务终端可以用以下默认参数。
  - 波特率: 115200, 数据位: 8 停止位: 1, 奇偶校验位: None。
- TCP/SSL
  - 对于网络通信，支付终端将作为服务端，自助服务终端将作为客户端进行通信。 默认的端口号为10009。

## 操作环境

### 支付终端

IM系列
IM30
IM700
IM15

# 通信协议

## 通信交互设计

该协议设计分为两层，一层为应用层，另一层为通信层。

- 应用层 (基于JSON，适用于所有通信方法)
- 通信层(不同的通信方式采用不同的逻辑)

## 应用层

采用JSON格式，命令的具体内容将放到该层实现

### 格式范例

一条发自自助服务终端的请求报文的一般如下:

    {
        "version": "2.xx",
        "request": [
            {
                "command": "CMD",
                "properties": {
                    "name1": "Value1",
                    "name2": "Value2"
                }
            }
        ]
    }

一条来自支付终端的响应报文的一般如下:

    {
        "version": "2.xx",
        "response": [
            {
                "command": "CMD",
                "properties": {
                    "name1": "Value1",
                    "name2": "Value2"
                }
            }
        ]
    }

## 通信层

在本章节中， "报文体" 指应用层数据内容。

### 通信方式

#### TCP/SSL

TCP/SSL完整报文包由报文头和报文体两部分组成。 报文头由协议标记，报文头长度，报文体长度等组成. 详细请参考 报文头格式。

格式:

报文头 | 报文体
--- | ---
PJ**** | {****}

#### UART/USB

UART/USB 完整报文包由起始符，报文头，报文体以及校验码组成。 报文头由协议标记，报文头长度，报文体长度等组成. 详细请参考 报文头格式。

格式:

起始符 | 报文头 | 报文体 | 校验码
--- | --- | --- | ---
STX | PJ**** | {****} | LRC

起始符: 固定值为'\x02'。单字节，ASCII码控制字符STX（标记有效数据的开始）。

校验码: 单字节。用来判断报文是否有效，计算方式为从报文头到报文体逐字节异或(排除起始符)。

校验码计算方式:

    Set LRC = 0
    For each character c in the package
    Do
    Set LRC = LRC XOR c
    End Do
    The check begins after the STX.

校验码计算示例:

    The algorithm is XOR calculation for each byte of data

    The hexadecimal format is 01 A0 7C FF 02
    01 xor A0 xor 7C xor FF xor 02 = 20
    The LRC is 20

### 通信控制

#### ACK

该报文用来确认消息已经被成功接收。当接收到一个完整的数据包，并且数据包格式是正确时，接收方需要回复一个ACK。 该报文在 TCP/SSL/UART/USB 中被使用。

格式: \x06

#### NAK

该报文用来反馈报文有问题。当接收到一个数据包，但该数据包数据有错。接收方需要回复一个NAK。 该报文在 UART/USB 中被使用。

格式: \x15

#### EOT

该报文用来标记当前通信已经结束。 当前支付终端在收到ACK后，会发送EOT给自助服务终端。 该报文在 TCP/SSL/UART/USB 中被使用。

格式: \x04

### 报文头格式

格式:

报文头标记 (2 Bytes) | 报文头长度 (3 Bytes) | 报文体长度 (6 Bytes) | 包序号 (3 Bytes) | 包状态 (1 Byte) | 协议类型 (2 Bytes)
--- | --- | --- | --- | --- | ---
PJ | 017 | 000200 | 000 | 0 | 01

- 报文头标记: POSLink JSON 协议. 必须为"PJ"。
- 报文头长度: 报文头的长度。 在上表中报文头长度为 17 (2+3+6+3+1+2 = 17).
- 报文体长度: 报文体的长度。 格式为 n6 (6位数的数字).
- 包序号: 预留字段，必须为000。
- 包状态: 预留字段，必须为0。
- 协议类型: 当前为UPT协议，必须为01。
- 报文头里出现的所有数字都是字符串格式。

示例: PJ017000100000001

# 通信场景

该章节介绍了本协议在不同场景下的传输过程以及内容。

## TCP/SSL

### 普通场景

自助服务终端发送命令前先建立连接，执行结束后断开连接。

一个成功的传输过程:

- Abort: 可选，取消当前正在执行的命令，不需要ACK。
- Report Status: 某些情况下会出现，报告当前状态给自助服务终端，不需要ACK。
- Abort 以及Report Status 并不一定会出现。详细请查看 命令定义。

成功传输

### 超时场景

接收消息超时，当接收端没有在指定时间收到完整的报文，那么将断开当前的连接。 超时时间定义如下:

- 请求报文超时: 3 秒
- ACK 超时: 9 秒
- EOT 超时: 1 秒
- 响应报文超时: 取决于自助服务终端设置，不同的命令可以采用不同的超时时间。推荐时间120秒。

请求报文超时/网络错误
请求报文ACK超时/网络错误
响应报文超时/网络错误
响应报文ACK 超时/网络错误
EOT 超时/网络错误

## UART/USB

### 普通场景

一个成功的传输过程:

- Abort: 可选，取消当前正在执行的命令，不需要ACK。
- Report Status: 某些情况下会出现，报告当前状态给自助服务终端，不需要ACK。
- Abort 以及Report Status 并不一定会出现。详细请查看 命令定义。

成功传输

### NAK场景

如果校验码(LRC)校验数据失败，那么接收方需要发送NAK来告诉发送方重发数据。 发送方重试3次，如果3次都失败，那么结束当前的重发。

重发请求报文3次, 成功
重发响应报文3次, 失败

### 超时场景

接收消息ACK超时，如果3秒内发送方没有收到确认成功的ACK，那么发送方需要重新发送，一共重试3次。 超时时间定义如下：

- ACK 超时: 3 秒
- EOT 超时: 1 秒
- 响应报文超时: 取决于自助服务终端设置，不同的命令可以采用不同的超时时间。推荐时间120秒。

等待请求报文ACK3次, 成功
等待响应报文ACK3次, 失败

# 一般交易流程

- 自助服务终端发送TransactionStart给PAX终端。
- 持卡人在PAX终端上完成操作。
- PAX终端和后台通信完成交易。
- PAX终端返回TransactionStart执行结果给自助服务终端。
- 自助服务终端处理自己的业务逻辑。
- 自助服务终端根据自身的执行结果发送TransactionCompletion或者TransactionReversal给PAX终端。
- PAX终端和后台通信后，返回TransactionCompletion或者TransactionReversal执行结果给自助服务终端。此次交易结束。

普通交易流程

# 命令数据属性

修饰符 | 含义
--- | ---
n | 数字，0 到 9
a | 字母 A-Z 以及 a-z
s | 特殊字符， 字母数字外的可打印字符
an | 字母以及数字
ans | 字母，数字以及特殊字符
YYYY | 年，0000 到 9999
YY | 年，00 到 99
MM | 月，01 到 12
DD | 日，01 到 31
hh | 时，00 到 23
mm | 分，00 到 59
ss | 秒，00 到 59

修饰符 | 含义
--- | ---
M | Mandatory, 必须字段
C | Conditional, 在某些条件下，该字段是必须字段
O | Optional, 可选字段

# 命令定义

## Admin

### GetTerminalInfo

获取终端信息。

#### 请求报文

本命令没有相关字段。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
sn | string | C | ans...16 | 设备的序列号。
modelName | string | C | ans...10 | 设备的型号。
osVersion | string | C | ans...64 | 操作系统的版本号。
appVersion | string | C | ans...32 | 应用版本。
appUpdateTimeStamp | string | C | n14 | 应用更新结束的时间戳。如果应用从来没有更新过，那么该字段不会出现。该时间戳格式YYYYMMDDhhmmss。该值和终端更新结束时的显示时间相同。
ipAddress | string | C | ans...15 | 当前在局域网中的IP地址。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"GetTerminalInfo"
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"GetTerminalInfo",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "sn":"*",
                    "modelName":"*",
                    "osVersion":"*",
                    "appVersion":"*",
                    "appUpdateTimeStamp":"*",
                    "ipAddress":"*"
                }
            }
        ]
    }

### Abort

当已经发送了命令A，并且终端正在等待用户操作，自助服务设备可以发送Abort命令来中断命令的执行，并收到命令A的执行结果。

#### 请求报文

本命令没有相关字段。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"Abort"
            }
        ]
    }

### Reboot

重启设备。

#### 请求报文

本命令没有相关字段。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"Reboot"
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"Reboot",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*"
                }
            }
        ]
    }

### Reset

重置终端屏幕到空闲状态。

#### 请求报文

本命令没有相关字段。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"Reset"
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"Reset",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*"
                }
            }
        ]
    }

### GetConfiguration

获取终端参数配置。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
names | string[] | O |  | 需要获取的配置参数名列表。请查看 GConfigurationNames。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
configurations | GConfigurationInfo[] | C |  | 从终端返回的配置信息。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"GetConfiguration",
                "properties":{
                    "names":["*"]
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"GetConfiguration",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "configurations":[{
                        "name":"*",
                        "value":"*"
                    }]
                }
            }
        ]
    }

### SetConfiguration

设置终端参数配置。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
configurations | SConfigurationInfo[] | O |  | 配置参数列表

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"SetConfiguration",
                "properties":{
                    "configurations":[{
                        "name":"*",
                        "value":"*"
                    }]
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"SetConfiguration",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*"
                }
            }
        ]
    }

### ReportStatus

报告当前的终端状态给自助服务设备. 本命令不需要请求报文。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
statusCode | string | M | n7 | 状态码
statusMessage | string | M | ans...64 | 状态消息。请查看 消息上报状态码。

#### 示例

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"ReportStatus",
                "properties":{
                    "statusCode":"*",
                    "statusMessage":"*"
                }
            }
        ]
    }

### Ping

Ping一个指定的服务器，测试网络是否工作正常。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
targetName | string | M | ans...256 | 目标名字，可以为IPv4的地址或者域名。
timeout | string | O | n...3 | 等待超时的时间，单位为100毫秒，(超时时间 = 字段值 * 100ms) 有效的取值区间为[30, 300]. 默认值为50。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
rtt | string | C | n...7 | 来回传输时间。单位为100ms(传输时间 = 字段值 * 100ms) 该值的取值方法为截断小数点后的位数，比如真实时间为199ms，那么在这里该值为1。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"Ping",
                "properties":{
                    "targetName":"*",
                    "timeout":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"Ping",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "rtt":"*"
                }
            }
        ]
    }

## Transaction

### TransactionStart

开始交易，命令成功后，必须要发送TransactionCompletion或者TransactionReversal来结束或者取消交易。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
transactionAmount | string | M | n...9 | 交易金额。 小数点位数取决于地域。 示例，在中国，该值包含两位小数，“1000”代表“10.00”元。 当支付终端处在demo模式下，使用特殊的金额去执行交易可以触发特殊的结果。 如果使用GetTraceInfoByCard来预处理交易，该值必须和GetTraceInfoByCard中的amount字段值一样。 如果使用GetCardStatus来预处理交易，该值必须和配置preprocessingAmount值一样，可以通过SetConfiguration命令配置。请查看 Demo模式特殊金额。
registerReferenceNumber | string | M | ans...32 | 交易流水号，自助服务终端可以用来标记一笔交易的唯一标识符。目前应用支持字母，数字和特殊字符“_”和“-”。
account | string | O | ans...19 | 从GetTraceInfoByCard/GetCardStatus命令返回的account字段值。如果需要使用GetTraceInfoByCard/GetCardStatus来预处理交易，那么你必须输入该字段。 当你设置了该字段: 1. 如果它和存储在支付终端的卡号相同，那么用户没有必要再次插卡/拍卡/刷卡。 2. 如果它和存储在支付终端的卡号不同，那么用户需要再次插卡/拍卡/刷卡。
reportStatus | string | O | n1 | 上报状态功能的开关。 0 = 关 (默认值) 1 = 开
hostGateway | HostGateway | O |  | RFU
accountInformation | AccountReq | O |  | RFU
enableCardUniqueIdentifier | string | O |  | 开启是否获取卡片唯一标识。默认值是“Off”。 请查看EnableCardUniqueIdentifier。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
hostReferenceNumber | string | C | ans...64 | 后台返回的交易流水号 TransactionCompletion和TransactionReversal命令中的originalHostReferenceNumber应使用该值。 如果交易失败该字段可能为空。
hostData | string | C | ans...256 | 后台返回的交易数据。 TransactionCompletion和TransactionReversal命令中的originalHostData应使用该值。 如果交易失败该字段可能为空。
account | string | C | ans...19 | 卡号，返回前6位以及后4位，其它用“*”代替。 示例: 545454*********5454。
timestamp | string | M | n14 | 交易时间戳，格式YYYYMMDDhhmmss.
accountInformation | AccountRsp | C |  | 卡片信息。
hostInformation | HostRsp | C |  | RFU
amountInformation | AmountRsp | C |  | 交易金额相关信息。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"TransactionStart",
                "properties":{
                    "transactionAmount":"*",
                    "registerReferenceNumber":"*",
                    "account":"*",
                    "reportStatus":"*",
                    "hostGateway":{
                        "tokenRequestFlag":"*",
                        "token":"*"
                    },
                    "accountInformation":{
                        "cardExpireDate":"*"
                    },
                    "enableCardUniqueIdentifier":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"TransactionStart",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "hostReferenceNumber":"*",
                    "hostData":"*",
                    "account":"*",
                    "timestamp":"*",
                    "accountInformation":{
                        "expireDate":"*",
                        "cardType":"*",
                        "cardTypeName":"*",
                        "cardUniqueIdentifier":"*"
                    },
                    "hostInformation":{
                        "token":"*"
                    },
                    "amountInformation":{
                        "approvedAmount":"*"
                    }
                }
            }
        ]
    }

### TransactionCompletion

正常完成一笔交易。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
transactionAmount | string | M | n...9 | 交易金额。 小数点位数取决于地域。 示例，在中国，该值包含两位小数，"1000"代表"10.00"元。 当支付终端处在demo模式下，使用特殊金额去执行交易可以触发特殊的结果。请查看 Demo模式特殊金额。
originalHostReferenceNumber | string | M | ans...64 | 原始的后台流水号，从TransactionStart命令执行结果的hostReferenceNumber获取。
originalHostData | string | M | ans...256 | 原始的后台数据。从TransactionStart命令执行结果的hostData获取。
verifyCard | string | O | n1 | [ 已废弃 ] 校验卡标记位。 0: 不校验(默认) 1: 校验。如果该卡与执行TransactionStart命令时使用的卡是同一张卡，交易会正常执行。如果不是，交易将停止。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
hostReferenceNumber | string | C | ans...64 | 后台返回的交易流水号。
hostData | string | C | ans...256 | 后台返回的交易数据。
timestamp | string | C | n14 | 交易时间，格式为YYYYMMDDhhmmss.
amountInformation | AmountRsp | C |  | 交易金额相关信息。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"TransactionCompletion",
                "properties":{
                    "transactionAmount":"*",
                    "originalHostReferenceNumber":"*",
                    "originalHostData":"*",
                    "verifyCard":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"TransactionCompletion",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "hostReferenceNumber":"*",
                    "hostData":"*",
                    "timestamp":"*",
                    "amountInformation":{
                        "approvedAmount":"*"
                    }
                }
            }
        ]
    }

### TransactionReversal

取消一笔交易，可以在TransactionStart命令成功之后，TransactionCompletion命令未执行前使用。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
originalHostReferenceNumber | string | M | ans...64 | 原始的后台流水号，从TransactionStart命令执行结果的hostReferenceNumber获取。
originalHostData | string | M | ans...256 | 原始的后台数据。从TransactionStart命令执行结果的hostData获取。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"TransactionReversal",
                "properties":{
                    "originalHostReferenceNumber":"*",
                    "originalHostData":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"TransactionReversal",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*"
                }
            }
        ]
    }

### TransactionIncremental

当顾客实际消费金额超过预设金额时使用，使用该命令增加金额到实际消费的金额。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
transactionAmount | string | M | n...9 | 待增加的金额，预设的金额+该字段值=实际消费的金额。 格式与TransactionStart里transactionAmount保持一致。
originalHostReferenceNumber | string | M | ans...64 | 原始的后台流水号，从TransactionStart命令执行结果的hostReferenceNumber获取。
originalHostData | string | M | ans...256 | 原始的后台数据。从TransactionStart命令执行结果的hostData获取。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
hostReferenceNumber | string | C | ans...64 | 后台返回的交易流水号。
hostData | string | C | ans...256 | 后台返回的交易数据。
timestamp | string | C | n14 | 交易时间，格式为YYYYMMDDhhmmss.
amountInformation | AmountRsp | C |  | 交易金额相关信息。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"TransactionIncremental",
                "properties":{
                    "transactionAmount":"*",
                    "originalHostReferenceNumber":"*",
                    "originalHostData":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"TransactionIncremental",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "hostReferenceNumber":"*",
                    "hostData":"*",
                    "timestamp":"*",
                    "amountInformation":{
                        "approvedAmount":"*"
                    }
                }
            }
        ]
    }

## Batch

### BatchClose

关闭当前的清结算处理。

#### 请求报文

本命令没有相关字段。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
hostData | string | C | ans...256 | 后台返回的交易数据。
totalCount | string | C | n...4 | 净存款计数。 不包含未完成和撤回的交易计数。
totalAmount | string | C | n...9 | 净存款金额。 不包含未结清和撤回的交易金额。
timeStamp | string | C | n14 | 时间戳，格式为YYYYMMDDhhmmss.

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"BatchClose"
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"BatchClose",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "hostData":"*",
                    "totalCount":"*",
                    "totalAmount":"*",
                    "timeStamp":"*"
                }
            }
        ]
    }

### BatchClear

清空本地数据库。

#### 请求报文

本命令没有相关字段。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"BatchClear"
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"BatchClear",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*"
                }
            }
        ]
    }

## Device

### MifareClassicRead

读取Mifare Classic卡。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
password | string | M | ans…32 | 授权密码，格式为16进制，最大长度为32。 示例: “01234567890123ABCDEF” 即为 “\x01\x23\x45\x67\x89\x01\x23\xAB\xCD\xEF”
passwordType | string | M | n1 | 密码类型： 0: A类型。 1: B类型。
blockNumber | string | M | n...3 | 块序号。格式为10进制，最大长度为3. 最大数值为255。
timeout | string | M | n...4 | 检测卡的超时时间，单位为100ms。有效值为[0, 9999]。 如果值为0，则表示立即返回。(超时时间=字段值* 100ms)

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
blockValue | string | C | an32 | 从卡上读到的结果。格式为16进制，长度为32。 示例： “01234567890123ABCDEF” 即为 “\x01\x23\x45\x67\x89\x01\x23\xAB\xCD\xEF”

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"MifareClassicRead",
                "properties":{
                    "password":"*",
                    "passwordType":"*",
                    "blockNumber":"*",
                    "timeout":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"MifareClassicRead",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "blockValue":"*"
                }
            }
        ]
    }

### MifareClassicWrite

写入Mifare Classic卡。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
password | string | M | ans…32 | 授权密码，格式为16进制，最大长度为32。 示例： “01234567890123ABCDEF” 即为 “\x01\x23\x45\x67\x89\x01\x23\xAB\xCD\xEF”。
passwordType | string | M | n1 | 密码类型： 0: A类型。 1: B类型。
blockNumber | string | M | n...3 | 块序号。格式为10进制，最大长度为3. 最大数值为255。
blockValue | string | M | ans32 | 待写入的值，格式为16进制，长度为32。 示例： “01234567890123ABCDEF” 即为 “\x01\x23\x45\x67\x89\x01\x23\xAB\xCD\xEF”。
timeout | string | M | n...4 | 检测卡的超时时间，单位为100ms。有效值为[0, 9999]。 如果值为0，则表示立即返回。(超时时间=字段值* 100ms)

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"MifareClassicWrite",
                "properties":{
                    "password":"*",
                    "passwordType":"*",
                    "blockNumber":"*",
                    "blockValue":"*",
                    "timeout":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"MifareClassicWrite",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*"
                }
            }
        ]
    }

### MifareClassicGetUID

获取Mifare Classic卡的UID。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
timeout | string | M | n...4 | 检测卡的超时时间，单位为100ms。有效值为[0, 9999]。 如果值为0，则表示立即返回。(超时时间=字段值* 100ms)

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
uid | string | C | an...20 | 从Mifare Classic卡获取到的UID。格式为16进制。 示例： “01234567” 即为 “\x01\x23\x45\x67”

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"MifareClassicGetUID",
                "properties":{
                    "timeout":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"MifareClassicGetUID",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "uid":"*"
                }
            }
        ]
    }

## Report

### GetTransactionInfo

获取交易信息。用于查询交易状态，确定交易是否已完成。 它还可用于获取交易数据以帮助跟踪交易。
只有当终端包含对应记录时，才会返回结果。 清结算操作后记录将被清除，交易失败时不记录。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
registerReferenceNumber | string | M | an...32 | 交易流水号，自助服务终端可以用来标记一笔交易的唯一标识符，与TransactionStart中的registerReferenceNumber字段相同。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
status | string | C | n1 | 交易状态 0: 已开始。 1: 已完成。 2: 已撤销。
hostData | string | C | ans...256 | 从后台返回的交易数据。 取决于status字段， 如果status字段为0 (已开始), 该值来自TransactionStart的执行结果。如果status字段为1 (已完成)，该值来自TransactionCompletion的执行结果。如果status字段为2(已撤销)，该值为空。
hostReferenceNumber | string | C | ans...64 | 从后台返回的交易流水号。 取决于status字段， 如果status字段为0 (已开始), 该值来自TransactionStart的执行结果。如果status字段为1 (已完成)，该值来自TransactionCompletion的执行结果。如果status字段为2(已撤销)，该值为空。
timeStamp | string | C | n14 | 交易时间，格式为YYYYMMDDhhmmss。 取决于status字段， 如果status字段为0 (已开始), 该值来自TransactionStart的执行结果。如果status字段为1 (已完成)，该值来自TransactionCompletion的执行结果。如果status字段为2(已撤销)，该值为空。
amountInformation | AmountRsp | C |  | 交易金额相关信息。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"GetTransactionInfo",
                "properties":{
                    "registerReferenceNumber":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"GetTransactionInfo",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "status":"*",
                    "hostData":"*",
                    "hostReferenceNumber":"*",
                    "timeStamp":"*",
                    "amountInformation":{
                        "approvedAmount":"*"
                    }
                }
            }
        ]
    }

### GetTraceInfoByCard

[ 已废弃 ] 自助服务终端发送请求让用户去拍卡/插卡/刷卡。支付终端等待用户完成相关操作，并返回相关的交易痕迹信息以及交易流水号和账号信息。与此同时，支付终端会将卡片信息保留一定时间(30s)，当发送下一条命令(TransactionStart)时，用户不需要重新拍卡/插卡/刷卡。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
timeout | string | M | ans...5 | 默认超时时间为30s。 有效值的取值范围为[-1, 9999]。如果值为0，那么意味着命令将立刻返回。如果值为-1，那么意味着终端将一直保持在等待状态。(超时时间 = 字段值 * 100ms)
transactionAmount | string | M | n...9 | 用来预处理交易，一些操作必须在有卡时完成。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
traceInfo | TraceInfo[] | C |  | 帮助跟踪交易的信息。如果一张卡开启了多笔交易并且都未完成，那么终端将返回和此卡相关的所有交易信息。
account | string | C | ans...19 | 卡号，返回前6位以及后4位，其它用'*'代替。示例: 545454*********5454。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"GetTraceInfoByCard",
                "properties":{
                    "timeout":"*",
                    "transactionAmount":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"GetTraceInfoByCard",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "traceInfo":[{
                        "registerReferenceNumber":"*",
                        "hostReferenceNumber":"*"
                    }],
                    "account":"*"
                }
            }
        ]
    }

### GetCardStatus

自助服务终端发送请求给支付终端，一旦确认用户拍卡/插卡/刷卡， 自助服务终端就可以发送TransactionStart命令。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
enableCardUniqueIdentifier | string | O |  | 开启是否获取卡片唯一标识。默认值是“Off”。 请查看EnableCardUniqueIdentifier。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
cardType | string | C | n1 | 卡片类型. 1：Credit/Debit卡 2：Mifare Classic（M1）卡，是遵守ISO14443A标准的非接触式IC卡，比如Mifare S50和Mifare S70系列。 如果没人拍卡/插卡/刷卡，该字段为空。
account | string | C | an...20 | 卡片的卡号或者UID。 当卡片类型为信用/借记卡时,返回前6位以及后4位，其它用“*”代替。 示例：545454*********5454 当卡片类型为M1卡时，返回卡片的UID。格式为16进制。 示例：“01234567” 即为 “\x01\x23\x45\x67” 如果没人拍卡/插卡/刷卡，该字段为空。
accountInformation | AccountRsp | C |  | 卡片信息。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"GetCardStatus",
                "properties":{
                    "enableCardUniqueIdentifier":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"GetCardStatus",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "cardType":"*",
                    "account":"*",
                    "accountInformation":{
                        "expireDate":"*",
                        "cardType":"*",
                        "cardTypeName":"*",
                        "cardUniqueIdentifier":"*"
                    }
                }
            }
        ]
    }

### GetCardInfo

自助服务终端发送请求让用户去拍卡/插卡/刷卡以获取卡号.获取的卡号被用来校验持卡人是否为同一人.

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
timeout | string | O | n...4 | 检测卡的超时时间，单位为100ms。有效值的取值范围为[-1, 9999]。 如果值为0，那么意味着命令将立刻返回。如果值为-1，那么意味着终端将一直保持在等待状态。(超时时间 = 字段值 * 100ms)
transactionAmount | string | C | n...9 | 用来预处理交易，一些操作必须在有卡时完成。
enableCardUniqueIdentifier | string | O |  | 开启是否获取卡片唯一标识。默认值是“Off”。 请查看EnableCardUniqueIdentifier。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
account | string | C | an...19 | 卡号，返回前6位以及后4位，其它用'*'代替。 示例: 545454*********5454 如果没人拍卡/插卡/刷卡，该字段为空。
accountInformation | AccountRsp | C |  | 卡片信息。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"GetCardInfo",
                "properties":{
                    "timeout":"*",
                    "transactionAmount":"*",
                    "enableCardUniqueIdentifier":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"GetCardInfo",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "account":"*",
                    "accountInformation":{
                        "expireDate":"*",
                        "cardType":"*",
                        "cardTypeName":"*",
                        "cardUniqueIdentifier":"*"
                    }
                }
            }
        ]
    }

## Form

### InputText

通过该指令可以让终端显示输入界面允许用户输入相关文本，例如邮箱和手机号。

#### 请求报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
title | string | M | ans...36 | 显示在输入界面的标题。
prompt | string | O | ans...256 | 显示在输入界面的提示信息。
inputType | string | M | ans...24 | 输入文本的类型: email: 邮箱 phoneNumber: 手机号
timeout | string | M | n...4 | 用户输入的超时时间，单位为100ms。有效值为[0, 9999]。 超时时间=字段值* 100ms
minLength | string | O | n...2 | 输入的最小长度，默认0，有效值[0,64]。
maxLength | string | O | n...2 | 输入的最大长度，默认64，有效值[1,64]。

#### 响应报文

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
responseCode | string | M | n6 | 响应码。请查看 响应码和响应消息 。
responseMessage | string | M | ans…64 | 响应消息。请查看 响应码和响应消息 。
inputText | string | C | ans...64 | 用户输入的文本。

#### 示例

请求报文

    {
        "version":"2.00",
        "request":[
            {
                "command":"InputText",
                "properties":{
                    "title":"*",
                    "prompt":"*",
                    "inputType":"*",
                    "timeout":"*",
                    "minLength":"*",
                    "maxLength":"*"
                }
            }
        ]
    }

响应报文

    {
        "version":"2.00",
        "response":[
            {
                "command":"InputText",
                "properties":{
                    "responseCode":"*",
                    "responseMessage":"*",
                    "inputText":"*"
                }
            }
        ]
    }

# 命令对象定义

## AccountReq

请求卡号信息。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
cardExpireDate | string | C | n...65 | RFU

## AccountRsp

命令返回的卡片信息。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
expireDate | string | C | n4 | 卡片的过期日期。格式为MMYY。
cardType | string | C |  | 卡片类型。 请查看CardType。
cardTypeName | string | C | a...32 | 卡片品牌名称。例如Cup指代China Union Pay。
cardUniqueIdentifier | string | C | ans...64 | 卡片唯一标识。

## AmountRsp

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
approvedAmount | string | C | n...9 | 通过的金额, 格式为$$$$$$$CC。 会返回该字段是因为不是所有请求的金额都会被完全通过。

## GConfigurationInfo

终端返回的配置信息。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
name | string | C |  | 配置参数名字。您可以在GConfigurationNames中找到所有参数名称。
value | string | C |  | 此参数的当前值。

## GConfigurationNames

可以获取配置名称。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
preprocessingAmount | string | O | n...9 | 预处理交易，如果希望终端默认预处理卡片，那么需要设置该值以启用该功能。然后才可以使用GetCardStatus命令。
currencyCode | string | O | n3 | 终端的货币代码,根据ISO 4217指示交易的货币代码。
tapImageName | string | O | ans...16 | 显示在支付终端的图片的名称，图片由客户提供。用户需按照以下规则定义： 最长为16位，需包含前缀CST_，后缀必须是.r 图片名举例：CST_XXXXX.r 图片类型支持PNG，BMP 当此项为空，表明关闭用户自定义显示界面，用户可以重新设置“tapPromptMsgLine1/tapPromptMsgLine2”显示默认界面。
tapPromptMsgLine1 | string | O | ans...30 | 当tapImageName未指定使用的自定义图片时，在Tap Any Time时显示在支付终端上的提示信息1。 当此项为空，显示默认信息。
tapPromptMsgLine2 | string | O | ans...40 | 当tapImageName未指定使用的自定义图片时，在Tap Any Time时显示在支付终端上的提示信息2。 当此项为空，显示默认信息。
cardReadSuccessMsg | string | O | ans...40 | 当tapImageName未指定使用的自定义图片时，读卡成功时显示在支付终端的附加提示信息。 当此项为空，显示默认信息。
displayMode | string | O | n1 | 该参数用于设置屏幕的显示方向： 0：代表横屏模式。 1：代表竖屏模式。 请注意，更改此参数后需要重启设备才能生效。 (仅支持IM15)
detectCardTimeout | string | O | n...4 | 等待检卡的超时的时间，单位为100毫秒，(超时时间 = 字段值 * 100ms) 有效的取值区间为[300，9999]. 默认值为300。 仅对TransactionStart命令有效。

## HostGateway

Host网关信息。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
tokenRequestFlag | string | O | n1 | RFU
token | string | O | ans...128 | RFU

## HostRsp

命令返回的Host信息。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
token | string | C | ans...128 | RFU

## SConfigurationInfo

用于设置终端的配置信息。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
name | string | O |  | 要设置的配置参数名称。您可以在SConfigurationNames中找到所有参数名称。
value | string | O |  | 要设置到参数的值。

## SConfigurationNames

可以设置的可配置参数名

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
preprocessingAmount | string | O | n...9 | 预处理交易，如果希望终端默认预处理卡片，那么需要设置该值以启用该功能。 然后才可以使用 GetCardStatus 命令。
tapImageName | string | O | ans...16 | 显示在支付终端的图片的名称，图片由客户提供。用户需按照以下规则定义： 最长为16位，需包含前缀CST_，后缀必须是.r 图片名举例：CST_XXXXX.r 图片类型支持PNG，BMP 当此项为空，表明关闭用户自定义显示界面，用户可以重新设置“tapPromptMsgLine1/tapPromptMsgLine2”显示默认界面。
tapPromptMsgLine1 | string | O | ans...30 | 当tapImageName未指定使用的自定义图片时，在Tap Any Time时显示在支付终端上的提示信息1。 当此项为空，显示默认信息。
tapPromptMsgLine2 | string | O | ans...40 | 当tapImageName未指定使用的自定义图片时，在Tap Any Time时显示在支付终端上的提示信息2。 当此项为空，显示默认信息。
cardReadSuccessMsg | string | O | ans...40 | 当tapImageName未指定使用的自定义图片时，读卡成功时显示在支付终端的附加提示信息。 当此项为空，显示默认信息。
displayMode | string | O | n1 | 该参数用于设置屏幕的显示方向： 0：代表横屏模式。 1：代表竖屏模式。 请注意，更改此参数后需要重启设备才能生效。 (仅支持IM15)
ipAddress | string | O | ans...15 | IP地址。
subnetMask | string | O | ans...15 | 子网掩码。
defaultGateway | string | O | ans...15 | 默认网关。
dnsServer | string | O | ans...15 | DNS服务器地址。
backgroundMode | string | O | a1 | 标记应用是否要在后台运行。Y：后台运行。N：必要情况下会在前台展示页面。
detectCardTimeout | string | O | n...4 | 等待检卡的超时的时间，单位为100毫秒，(超时时间 = 字段值 * 100ms) 有效的取值区间为[300，9999]. 默认值为300。 仅对TransactionStart命令有效。

## TraceInfo

可以帮助追踪一笔交易的信息。

参数名 | 类型 | 是否必需 | 属性 | 描述
--- | --- | --- | --- | ---
registerReferenceNumber | string | C | an...32 | 交易流水号，自助服务终端可以用来标记一笔交易的唯一标识符。
hostReferenceNumber | string | C | ans...64 | 后台返回的交易流水号。 TransactionCompletion和TransactionReversal命令的originalHostReferenceNumber应使用该值。

# 常量值定义

## CardType

值 | 描述
--- | ---
01 | VISA
02 | Mastercard
03 | AMEX
04 | Discover
05 | Diners Club
18 | China Union Pay
19 | Maestro
99 | 如果卡片类型未出现在列表中，使用其作为类型。

## EnableCardUniqueIdentifier

值 | 描述
--- | ---
Off | 不获取卡片唯一标识。
On | 获取卡片唯一标识。

# 常量值定义

## 响应码和响应消息

响应码 | 响应消息 | 备注
--- | --- | ---
000000 | OK | 对于交易命令，返回"OK"代表交易成功。 对于其它命令，返回"OK"代表命令执行成功。
110000 | HOST ERROR MESSAGE | 后台拒绝，返回后台的错误消息。
110000 | HOST ERROR CODE-HOST ERROR MESSAGE | 后台拒绝，返回后台的错误码以及错误消息，以"-"隔开。
110001 | EMV ERROR CODE-EMV ERROR MESSAGE | EMV错误，返回EMV错误码和错误消息。以"-"隔开。
110002 | FORMAT ERROR | 自助服务终端发送的消息格式错误，返回具体的错误信息，下面同一个错误代码的是可能的错误消息。
110002 | TRANSACTION AMOUNT INVALID | transactionAmount 字段无效。 1. 长度超过限制。 2. 无效的字符: 包含 "."，"-". 3. 金额为 "0".
110002 | TRANSACTION AMOUNT NOT ALLOWED | 在零售模式下金额不允许出现在TransactionCompletion命令中。
110002 | REGISTER REFERENCE NUMBER INVALID | 请检查 "registerReferenceNumber" 参数。
110002 | ORIGINAL HOST REFERENCE NUMBER INVALID | 请检查 "originalHostReferenceNumber" 参数。
110002 | ORIGINAL HOST DATA INVALID | 请检查 "originalHostData" 参数。
110002 | REPORT STATUS INVALID | 请检查 "reportStatus" 参数。
110002 | PASSWORD INVALID | 请检查 "password" 参数。
110002 | PASSWORD TYPE INVALID | 请检查 "passwordType" 参数。
110002 | BLOCK NUMBER INVALID | 请检查 "blockNumber" 参数。
110002 | TIMEOUT INVALID | 请检查 "timeout" 参数。
110002 | BLOCK VALUE INVALID | 请检查 "blockValue" 参数。
110002 | VERIFY CARD INVALID | verifyCard 参数应该是0或者1。
110002 | TARGET NAME INVALID | targetName 参数应该是IPv4地址或者域名。
110002 | MINLENGTH INVALID | 请查看"minLength"参数。
110002 | MAXLENGTH INVALID | 请查看"maxLength"参数。
110002 | TITLE INVALID | 请查看"title"参数。
110002 | PROMPT INVALID | 请查看"prompt"参数。
110002 | INPUTTYPE INVALID | 请查看"inputType"参数。
110002 | MIN EXCEED MAX | 请查看"minLength"和"maxLength"参数。
110002 | TRACK INVALID | 磁道数据错误。
110002 | EXP DATE INVALID | 1. 长度不对。 2. 无效的日期格式，月大于12或者日期大于31。 3. 非数字。
110002 | TOKEN REQUEST FLAG INVALID | 请检查“tokenRequestFlag”字段。
110002 | ENABLE CARD UNIQUE IDENTIFIER INVALID | 请检查 "enableCardUniqueIdentifier" 参数。
110100 | UNSUPPORTED COMMAND | 该命令不支持。
110101 | TIMEOUT | 等待用户操作超时。
110102 | ABORTED | 用户取消了当前命令。
110103 | CARD EXPIRED | 卡过期。
110104 | FALLBACK TO SWIPE NOT ALLOWED | 不允许回滚到刷卡。
110105 | UNSUPPORTED CARD TYPE | 不支持的卡类型。
110106 | CARD TYPE DISABLED | 该类型卡已经被禁用。
110107 | NEED REMOVE CARD FIRST | 需要先移除卡片。
110108 | SEE PHONE | 请看下手机，该交易需要重新开始。
110109 | HOST SEND ERROR | 终端发送消息给后台失败。
110110 | HOST RECEIVE ERROR | 终端从后台接收消息失败。
110111 | HOST CONNECT ERROR | 终端连接后台错误。
110112 | NETWORK UNAVAILABLE | 网络不可用。
110113 | PINPAD ERROR | PINPAD 错误。
110114 | DUPLICATE TRANSACTION | 重复的交易，在一次清结算处理中用了相同的register reference number。
110115 | ALREADY REVERSED | 该交易已经被撤销。
110116 | ALREADY COMPLETED | 该交易已经完成。
110117 | PLEASE BATCH | 请做清结算处理。
110118 | DATA STORAGE KEY MISSING | 数据存储密钥丢失。
110119 | P2PE KEY MISSING | P2PE密钥丢失。
110120 | TRANSACTION NOT FOUND | 根据originalHostReferenceNumber或者registerReferenceNumber没有找到对应的交易。
110121 | NOT SAME CARD | 当verifyCard开关打开时，发现执行TransactionCompletion命令时使用的卡和执行TransactionStart命令时不是同一张卡。
110122 | CARD INFO EXPIRED | 卡信息过期，在一些场景中，在完成GetCardStatus命令后，你需要及时发送TransactionStart命令。
110123 | ACCOUNT MISMATCH | TransactionStart请求中的account字段不匹配用户输入的账号。当自助终端指定账号，但该账号与终端缓存不匹配时，终端会要求重新刷卡/拍卡/插卡。当输入账户与TransactionStart请求中的账户不同时会出现此错误。
110124 | AMOUNT MISMATCH | TransactionStart请求中的amount字段不匹配GetTraceInfoByCard中的amount字段。由于卡片的处理流程，如果使用GetTraceInfoByCard对卡片进行预处理，GetTraceInfoByCard中的金额必须与GetTraceInfoByCard中的金额相同。
110125 | PREPROCESSING AMOUNT MISSING | 请先使用SetConfiguration命令设置preprocessingAmount参数。相关功能基于此配置。
110126 | SET CONFIGURATION ERROR: XXX,XXX | SetConfiguration命令参数错误，没有配置会被设置。该消息包含了有哪些配置参数名导致了命令失败(XXX 就是配置参数名)。该错误发生在以下情况：1.配置参数名错误，使用了没在SConfigurationNames出现过的名字。 2. 设置值错误，请检查相关配置的设置要求。
110127 | GET CONFIGURATION ERROR: XXX,XXX | GetConfiguration命令参数错误，没有配置会被返回。该消息包含了有哪些配置参数名导致了命令失败(XXX 就是配置参数名)。该错误为配置参数名错误，使用了没在GConfigurationNames出现过的名字。
110128 | PING DOMAIN NAME RESOLVE ERROR | Ping服务器时解析域名失败。
110129 | PING TIMEOUT | Ping服务器超时。
110130 | AMOUNT OVER CONTACTLESS LIMIT | 交易金额超过了非接交易的限制。仅适用于仅支持非接触卡的终端。
110131 | IP CONFIGURATION DISABLED IN DHCP | 在DHCP模式下不能配置IP。
110132 | IP CONFIGURATION PARAMETER ERROR | 必须一次性设置所有与IP相关的参数。IP相关参数包括ipAddress、subnetMask、defaulgateway、dnsServer。
110133 | PIN KEY MISSING | PIN密钥丢失。
110134 | PIN KEY AND P2PE KEY MISSING | PIN 和P2PE 密钥丢失。
110200 | INTERFACE CHIP DOES NOT EXIST OR ABNORMAL | 接口芯片不存在或异常。
110201 | PARAMETER ERROR | 参数错误。
110202 | RF MODULE IS CLOSED | RF（射频）模块关闭。
110203 | NOT DETECT CARD | 感应区域内没有卡，或该卡未激活。
110204 | COMMUNICATION CONFLICT | 感应区卡太多，通讯冲突。
110205 | PROTOCOL ERROR | 协议错误，卡的数据响应违反协议。
110206 | CARD NOT ACTIVATED | 卡未激活。
110207 | MULTI-CARD CONFLICT | 多卡冲突。
110208 | NO RESPONSE TIMEOUT | 没有响应超时。
110209 | PROTOCOL ERROR | 协议错误。
110210 | COMMUNICATION TRANSMISSION ERROR | 通讯传输错误。
110211 | MIFARE CLASSIC CARD AUTHENTICATION FAILURE | Mifare Classic卡认证失败。
110212 | SECTOR IS NOT CERTIFIED | 未指定扇区。
110213 | VALUE BLOCK FORMAT ERROR | 数据块值的数据格式不正确。
110214 | CARD IS STILL IN SENSING AREA | 卡仍在感应区。
110215 | CARD STATUS ERROR | 卡状态错误。
110216 | PARAMETER INVALID | 参数错误。
110217 | RPC I/O ERROR | RPC I/O 错误。
110218 | NOT SUPPORT FOR THIS DEVICE | 不支持此设备。
110219 | NOT PERMISSION FOR PICC | 不允许 PICC。
110220 | RPC BUSY | RPC繁忙。
110221 | AUTOMATIC REBOOT COUNTDOWN | 应用已经锁定，设备正在准备重启。
110222 | CARD EXPIRE DATE MISSING | 卡片过期时间对于tokenize交易是必要字段。请设置该值。
110223 | SERVICE BUSY | 服务繁忙。
110224 | PARAMETERS FILE CORRUPTION | 参数导入失败或参数文件损坏。
110225 | NEED READ CARD FIRST | 支付终端在执行此操作前需要先读卡。
110300 | PARTIALLY APPROVED | 部分金额通过。

## 消息上报状态码

状态码 | 状态消息 | 描述
--- | --- | ---
9000000 | Waiting For Card Operation | 等待刷卡/拍卡/插卡。(对于IM700，自助服务终端应该显示"Please Tap Card"，当收到一个新的状态码后清空显示。)
9000001 | Waiting For PIN Entry | 等待输入PIN。
9000003 | Online Processing | 在线处理中，正在和后台通信。
9000006 | Waiting For PIN Re-entry | 输入错误，等待重新输PIN。
9000007 | Please See Phone | 持卡人需要去检查他/她的手机。 (对于IM700，自助服务终端应该显示该消息，当收到一个新的状态码后清空显示。)
9000008 | Waiting For Try Another Card | 持卡人需要去尝试使用另一张卡。
9000009 | Please Present One Card Only | 持卡人需要只使用一张卡。 (对于IM700，自助服务终端应该显示该消息，当收到一个新的状态码后清空显示。)
9000010 | Fallback, Waiting For Swipe | 读取芯片卡失败，需要回滚到刷卡。
9000011 | Waiting For Remove Card | 需要移除卡片。
9000012 | Waiting For Re-Insert Card | 持卡人需要重新插卡。

# 附录

## Demo模式特殊金额

序号 | 交易金额 | 交易结果
--- | --- | ---
1 | 2001 | 授权拒绝
2 | 2002 | 无效卡片