版本：1.1.1

SSK POS HTTP Server 接口文档

版本号	编辑者	更新时间	更新内容
V1.0.0	房杨平	2025/07/25	完善功能

接口介绍

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

请求方式

任何可以发起 HTTP 请求的技术都可以使用。POST请求: http://[POS IP]:8090/[接口]

公共请求参数信息

参数名	类型	是否必填	描述
`requestId`	`String`	否	调用方唯一请求流水号
`cashierNo`	`String`	否	收银员编号，用于标识操作人员

公共响应参数信息

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

公共响应结构

{
  "code": "00",
  "msg": "SUCCESS",
  "data": {
    "requestId": "971dda25-8638-4ef1-b139-10f7661599a4",
    "sn": "247KCASL1947",
    "..."
  }
}

响应码定义表

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

接口列表

签到

接口：`/sign`

请求示例

curl --location --request POST 'http://172.16.46.132:8080/sign'

响应参数

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

示例

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

查询签到信息

接口：`/query/device/status`

curl --location --request POST 'http://172.16.46.132:8080/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":"SI00005958",
    "signStatus":"YES",
    "merchantNo":"4276000064",
    "defaultAmount":"45.00",
    "showButton":"SHOW",
    }
}

消费

接口: `/sale`

参数说明

字段名	类型	是否必传	字段说明
`paymentType`	`String`	是	支付类型: `01`-银行卡，`04`-二维码(B 扫 C)，`05`-二维码(C 扫 B) `06`-支付卡
`paymentSubType`	`String`	否	支付子类型: 只有 paymentType=06 必传: `12`-八达通
`merchantSerialNo`	`String`	是	商户交易流水号: 需保证全局唯一性
`orderAmount`	`String`	是	订单金额: 最小值为 0.01，两位小数）
`walletType`	`String`	否	钱包类型: paymentType=05 时选填 :`01`-微信，`02`-支付宝，`03`-云闪付，`04`-PayNow，`05`-PayMe
`externalAdditionalData`	`String`	否	附加信息
`mode`	`String`	否	`sync`-同步，`async`-异步，默认同步

请求示例

curl --location --request POST 'http://172.16.46.132:8080/sale' \
--data-urlencode 'requestId=98ed63fc-89bd-4b58-aa88-487b25de984f' \
--data-urlencode 'paymentType=01' \
--data-urlencode 'merchantSerialNo=5317b040-40ef-409c-a260-4c92a4d38d54' \
--data-urlencode 'orderAmount=20.00' \
--data-urlencode 'externalAdditionalData="{\"key1\":\"value1\",\"key2\":\"value2\"}"' \
--data-urlencode 'mode=sync'

响应参数

字段名	类型	字段说明
`merchantSerialNo`	`String`	商户交易流水号
`orderNo`	`String`	系统生成的唯一订单号
`transactionNo`	`String`	交易流水号（全局唯一）
`currency`	`String`	交易币种（ISO 4217 标准，如：`CNY`）
`totalAmount`	`String`	支付总金额
`orderAmount`	`String`	订单金额
`tipAmount`	`String`	小费金额
`payerFee`	`String`	交易手续费金额
`transactionStatus`	`String`	交易状态，参考附录枚举值
`paymentWay`	`String`	支付方式，参考附录枚举值
`paymentType`	`String`	支付类型，参考附录枚举值
`paymentSubType`	`String`	支付子类型，参考附录枚举值
`cardType`	`String`	卡类型，参考附录枚举值
`cardFlag`	`String`	卡标识，参考附录枚举值
`cardBrand`	`String`	卡组织，参考附录枚举值
`cardNoMask`	`String`	脱敏卡号（如：`6214*****5678`）
`posBatchNo`	`String`	POS 终端批次号
`posSerialNo`	`String`	POS 终端流水号
`retrievalNo`	`String`	检索参考号
`authCode`	`String`	交易授权码（联机交易返回）
`transactionTime`	`String`	交易发起时间
`completionTime`	`String`	交易完成时间

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "requestId": "5b80ac3e-0f69-4395-8886-ad09f8337504",
        "sn": "SI00005958",
        "api": "/sale",
        "merchantSerialNo": "5798e163-64b6-46aa-a321-100a5d21e0a3",
        "orderNo": "10820250725000011341",
        "transactionNo": "TK8E20BC445400000843966473240576",
        "currency": "HKD",
        "totalAmount": "20.00",
        "orderAmount": "20.00",
        "tipAmount": "0.00",
        "payerFee": "0.00",
        "transactionStatus": "00",
        "paymentWay": "01",
        "paymentType": "01",
        "paymentSubType": "03",
        "cardBrand": "01",
        "cardNoMask": "433668******3008",
        "posBatchNo": "250725",
        "posSerialNo": "000012",
        "retrievalNo": "520608288586",
        "authCode": "704583",
        "transactionTime": "2025-07-25T08:15:42.000+00:00",
        "completionTime": "2025-07-25T08:15:43.000+00:00"
    }
}

消费撤销

接口: `/sale/revoke`

请求参数说明

参数名	类型	是否必填	描述
`originalTransactionNo`	`String`	是	原预授权交易流水号
`merchantSerialNo`	`String`	是	商户交易流水号（需保证全局唯一性）

请求示例

curl --location --request POST 'http://172.16.46.132:8080/sale/revoke?requestId=0bc18b7e-85bf-4894-81ad-938930796f7c&originalTransactionNo=TK0E84A2A16C00000844002829369344&merchantSerialNo=24018b1d-b57c-439f-a5a0-7719cfc8c42c'

响应参数

字段名	类型	描述
`transactionNo`	`String`	交易流水号，本次撤销交易生成的流水号
`originalTransactionNo`	`String`	需要撤销的原交易流水号
`merchantSerialNo`	`String`	原交易对应的商户流水号
`orderNo`	`String`	订单号
`transactionStatus`	`String`	交易状态，参考附录枚举值
`orderAmount`	`String`	原交易订单金额
`transactionTime`	`String`	交易发起时间

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "requestId": "054d6a7d-6a6e-458e-8383-9b304b6fa1d2",
        "sn": "SI00005958",
        "api": "/sale/revoke",
        "transactionNo": "TK5DF9049A6B00000844003054649344",
        "originalTransactionNo": "TK0E84A2A16C00000844002829369344",
        "merchantSerialNo": "4ae2b31e-bf09-4472-8465-8e9aa47a6667",
        "orderNo": "10820250725000011346",
        "transactionStatus": "00",
        "orderAmount": "20.00",
        "transactionTime": "2025-07-25T08:52:55.000+00:00"
    }
}

预授权

接口: `/auth`

请求参数说明

参数名	类型	是否必填	描述
`merchantSerialNo`	`String`	是	商户交易流水号（需保证全局唯一性）
`orderAmount`	`String`	是	订单金额（最小值为0.01，单位：元，两位小数）
`externalAdditionalData`	`String`	否	附加信息
`mode`	`String`	否	`sync`-同步，`async`-异步，默认同步

请求示例

curl --location --request POST 'http://172.16.46.132:8080/auth' \
--data-urlencode 'requestId=5fbdecb5-96e8-4c68-8ea0-4db15011bf61' \
--data-urlencode 'sn=SI00004979' \
--data-urlencode 'merchantSerialNo=40e6ce5e-468a-4278-99cc-f31ebc240428' \
--data-urlencode 'orderAmount=1.55' \
--data-urlencode 'mode=sync' \
--data-urlencode 'externalAdditionalData="{\"key1\":\"value1\",\"key2\":\"value2\"}"'

响应参数说明

字段名	类型	字段说明
`merchantSerialNo`	`String`	商户交易流水号
`orderNo`	`String`	系统生成的唯一订单号
`transactionNo`	`String`	交易流水号（全局唯一）
`currency`	`String`	交易币种（ISO 4217 标准，如：`CNY`）
`totalAmount`	`String`	支付总金额
`orderAmount`	`String`	订单金额
`tipAmount`	`String`	小费金额
`payerFee`	`String`	交易手续费金额
`transactionStatus`	`String`	交易状态，参考附录枚举值
`paymentWay`	`String`	支付方式，参考附录枚举值
`paymentType`	`String`	支付类型，参考附录枚举值
`paymentSubType`	`String`	支付子类型，参考附录枚举值
`cardType`	`String`	卡类型，参考附录枚举值
`cardFlag`	`String`	卡标识，参考附录枚举值
`cardBrand`	`String`	卡组织，参考附录枚举值
`cardNoMask`	`String`	脱敏卡号（如：`6214*****5678`）
`posBatchNo`	`String`	POS 终端批次号
`posSerialNo`	`String`	POS 终端流水号
`retrievalNo`	`String`	检索参考号
`authCode`	`String`	交易授权码（联机交易返回）
`transactionTime`	`String`	交易发起时间
`completionTime`	`String`	交易完成时间

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "requestId": "ccba7775-dc38-48ad-b466-c42402084889",
        "sn": "SI00005958",
        "api": "/auth",
        "merchantSerialNo": "6d98c43b-4642-4438-8bd7-b42d22efd7b7",
        "orderNo": "10820250725000011347",
        "transactionNo": "TK999B0FDEB400000844009243394048",
        "currency": "HKD",
        "totalAmount": "1.55",
        "orderAmount": "1.55",
        "tipAmount": "0.00",
        "payerFee": "0.00",
        "transactionStatus": "00",
        "paymentWay": "01",
        "paymentType": "01",
        "paymentSubType": "03",
        "cardBrand": "01",
        "cardNoMask": "433668******3008",
        "posBatchNo": "250725",
        "posSerialNo": "000015",
        "retrievalNo": "520608288632",
        "authCode": "911384",
        "transactionTime": "2025-07-25T08:59:12.000+00:00",
        "completionTime": "2025-07-25T08:59:13.000+00:00"
    }
}

预授权撤销

接口: `/auth/revoke`

请求参数说明

参数名	类型	是否必填	描述
`originalTransactionNo`	`String`	是	原预授权交易流水号
`merchantSerialNo`	`String`	是	商户交易流水号（需保证全局唯一性）

请求示例

curl --location --request POST 'http://172.16.46.132:8080/auth/revoke?requestId=1264cc2b8f-8cc5-4c70-bb8f-9e3ae049dc31&originalTransactionNo=TK999B0FDEB400000844009243394048&merchantSerialNo=510b1d10-a661-47b5-931f-57f6a60e4d19'

响应参数说明

字段名	类型	描述
`transactionNo`	`String`	交易流水号，本次撤销交易生成的流水号
`originalTransactionNo`	`String`	需要撤销的原交易流水号
`merchantSerialNo`	`String`	原交易对应的商户流水号
`orderNo`	`String`	订单号
`transactionStatus`	`String`	交易状态，参考附录枚举值
`orderAmount`	`String`	原交易订单金额
`transactionTime`	`String`	交易发起时间

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "requestId": "125ac66c57-3647-425f-ae8f-c42719eb819a",
        "sn": "SI00005958",
        "api": "/auth/revoke",
        "transactionNo": "TKB90081E9CD00000844011693539328",
        "originalTransactionNo": "TK999B0FDEB400000844009243394048",
        "merchantSerialNo": "501ef667-3f1a-4191-add1-5e912263ac84",
        "orderNo": "10820250725000011347",
        "transactionStatus": "00",
        "orderAmount": "1.55",
        "transactionTime": "2025-07-25T09:01:42.000+00:00"
    }
}

交易查询

接口: `/query/transaction`

请求参数说明

参数名	类型	是否必填	描述
`originalTransactionNo`	`String`	否	原交易流水号
`merchantSerialNo`	`String`	否	原商户交易流水号

请求示例

curl --location --request POST 'http://172.16.46.132:8080/query/transaction' \
--data-urlencode 'requestId=12740e8a93-aee2-45ed-a859-31a011c8e257' \
--data-urlencode 'originalTransactionNo=TK999B0FDEB400000844009243394048'

响应参数说明

字段名	类型	字段说明
`merchantSerialNo`	`String`	商户交易流水号
`orderNo`	`String`	系统生成的唯一订单号
`transactionNo`	`String`	交易流水号（全局唯一）
`currency`	`String`	交易币种（ISO 4217 标准，如：`CNY`）
`totalAmount`	`String`	支付总金额
`orderAmount`	`String`	订单金额
`tipAmount`	`String`	小费金额
`payerFee`	`String`	交易手续费金额
`transactionStatus`	`String`	交易状态，参考附录枚举值
`paymentWay`	`String`	支付方式，参考附录枚举值
`paymentType`	`String`	支付类型，参考附录枚举值
`paymentSubType`	`String`	支付子类型，参考附录枚举值
`cardType`	`String`	卡类型，参考附录枚举值
`cardFlag`	`String`	卡标识，参考附录枚举值
`cardBrand`	`String`	卡组织，参考附录枚举值
`cardNoMask`	`String`	脱敏卡号（如：`6214*****5678`）
`posBatchNo`	`String`	POS 终端批次号
`posSerialNo`	`String`	POS 终端流水号
`retrievalNo`	`String`	检索参考号
`authCode`	`String`	交易授权码（联机交易返回）
`transactionTime`	`String`	交易发起时间
`completionTime`	`String`	交易完成时间

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "requestId": "120d412851-a918-4995-bf74-578f4a65562b",
        "sn": "SI00005958",
        "api": "/query/transaction",
        "merchantSerialNo": "6d98c43b-4642-4438-8bd7-b42d22efd7b7",
        "orderNo": "10820250725000011347",
        "transactionNo": "TK999B0FDEB400000844009243394048",
        "currency": "HKD",
        "totalAmount": "1.55",
        "orderAmount": "1.55",
        "tipAmount": "0.00",
        "payerFee": "0.00",
        "transactionStatus": "00",
        "paymentWay": "01",
        "paymentType": "01",
        "paymentSubType": "03",
        "cardBrand": "01",
        "cardNoMask": "433668******3008",
        "posBatchNo": "250725",
        "posSerialNo": "000015",
        "retrievalNo": "520608288632",
        "authCode": "911384",
        "transactionTime": "2025-07-25T08:59:12.000+00:00",
        "completionTime": "2025-07-25T08:59:13.000+00:00"
    }
}

设置营业

接口：`/open/business`

请求参数

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

请求示例

curl --location --request POST 'http://172.16.46.132:8080/open/business'

响应参数

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

示例

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

设置停业

接口：`/stop/business`

请求参数

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

请求示例

curl --location --request POST 'http://172.16.46.132:8080/stop/business'

响应参数

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

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "requestId": "880186bc-07eb-4f0b-b82d-d84a44dc466e",
        "sn": "SI00005958",
        "api": "/stop/business",
        "businessStatus": "CLOSE"
    }
}

查询营业状态

接口：`/query/business/status`

请求参数

公共请求参数

请求示例

curl --location --request POST 'http://172.16.46.132:8080/query/business/status'

响应参数

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

示例

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

完成交易

接口：`/finish/transaction`

请求参数

公共请求参数

请求示例

curl --location --request POST 'http://172.16.46.132:8080/finish/transaction'

响应参数

公共返回参数

示例

{
  "code":"00",
  "msg":"SUCCESS",
  "data":{
    "api":"/finish/transaction",
    "sn":"3080004570",
    "businessStatus":"OPEN",
    }
}

取消交易

接口：`/cancel/transaction`

请求参数

公共请求参数

请求示例

curl --location --request POST 'http://172.16.46.132:8080/cancel/transaction'

响应参数说明

公共返回参数

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "sn": "SI00005958",
        "api": "/cancel/transaction"
    }
}

接口介绍​

请求方式​

公共请求参数信息​

公共响应参数信息​

公共响应结构​

响应码定义表​

接口列表​

签到​

接口：/sign​

请求示例​

响应参数​

查询签到信息​

接口：/query/device/status​

响应参数​

消费​

接口: /sale​

参数说明​

请求示例​

响应参数​

消费撤销​

接口: /sale/revoke​

请求参数说明​

请求示例​

响应参数​

预授权​

接口: /auth​

请求参数说明​

请求示例​

响应参数说明​

预授权撤销​

接口: /auth/revoke​

请求参数说明​

请求示例​

响应参数说明​

交易查询​

接口: /query/transaction​

请求参数说明​

请求示例​

响应参数说明​

设置营业​

接口：/open/business​

请求参数​

请求示例​

响应参数​

设置停业​

接口：/stop/business​

请求参数​

请求示例​

响应参数​

查询营业状态​

接口：/query/business/status​

请求参数​

请求示例​

响应参数​

完成交易​

接口：/finish/transaction​

请求参数​

请求示例​

响应参数​

取消交易​

接口：/cancel/transaction​

请求参数​

请求示例​

响应参数说明​

接口介绍

请求方式

公共请求参数信息

公共响应参数信息

公共响应结构

响应码定义表

接口列表

签到

接口：`/sign`

请求示例

响应参数

查询签到信息

接口：`/query/device/status`

响应参数

消费

接口: `/sale`

参数说明

请求示例

响应参数

消费撤销

接口: `/sale/revoke`

请求参数说明

请求示例

响应参数

预授权

接口: `/auth`

请求参数说明

请求示例

响应参数说明

预授权撤销

接口: `/auth/revoke`

请求参数说明

请求示例

响应参数说明

交易查询

接口: `/query/transaction`

请求参数说明

请求示例

响应参数说明

设置营业

接口：`/open/business`

请求参数

请求示例

响应参数

设置停业

接口：`/stop/business`

请求参数

请求示例

响应参数

查询营业状态

接口：`/query/business/status`

请求参数

请求示例

响应参数

完成交易

接口：`/finish/transaction`

请求参数

请求示例

响应参数

取消交易

接口：`/cancel/transaction`

请求参数

请求示例

响应参数说明