版本：1.1.1

收单POS HTTP Server 接口文档

版本号	编辑者	更新时间	更新内容
V1.0.0	房杨平	2025/07/25	完善功能
V1.1.0	房杨平	2025/12/19	完善补充Api接口

接口介绍

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

请求方式

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

公共请求参数信息

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

公共响应参数信息

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

公共响应结构

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

响应码定义表

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

接口列表

查询签到信息

接口：`/query/device/status`

curl --location --request POST "http://192.168.22.57:8090/query/device/status"

响应参数

参数名	类型	描述
`signStatus`	`String`	签到状态 `0: 未签到` `1: 已签到`
`merchantNo`	`String`	商户号

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "api": "/query/device/status",
        "sn": "NCBA01646473",
        "signStatus": "1",
        "merchantNo": "1344000083"
    }
}

签到

接口：`/sign`

请求示例

curl --location --request POST 'http://192.168.22.57:8090/sign' \
--data-urlencode 'signType=1'

响应参数

参数名	类型	描述
`signType`	`String`	签到状态 `0: 签到` `1: 签到`

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "api": "/sign",
        "sn": "NCBA01646473",
        "signStatus": "1",
        "merchantNo": "1344000083"
    }
}

消费

接口: `/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'

响应参数

字段名	类型	字段说明
`merchantOrderNo`	`String`	商户交易订单号
`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`	交易完成时间
`externalAdditionalData`	`String`	附加信息

示例

{
    "code": "00",
    "msg": "SUCCESS",
    "data": {
        "api": "/sale",
        "sn": "NCBA01646473",
        "merchantOrderNo": "4032842605494298",
        "merchantSerialNo": "e50c0f5c-c2c8-4bcc-ac0a-5bf5bf09b03a",
        "orderNo": "10820251219000030022",
        "transactionNo": "TK97C348952500001055219889635328",
        "currency": "HKD",
        "totalAmount": "0.55",
        "orderAmount": "0.55",
        "tipAmount": "0.00",
        "payerFee": "0.00",
        "transactionStatus": "00",
        "paymentWay": "01",
        "paymentType": "01",
        "cardBrand": "01",
        "cardNoMask": "451461****7853",
        "posBatchNo": "251219",
        "posSerialNo": "000001",
        "retrievalNo": "535305362891",
        "authCode": "072905",
        "transactionTime": "2025-12-19T05:58:21.000+00:00",
        "completionTime": "2025-12-19T05:58:22.000+00:00",
        "externalAdditionalData": "\"{\\\"key1\\\":\\\"value1\\\",\\\"key2\\\":\\\"value2\\\"}\""
    }
}

撤销

接口: `/revoke`

请求参数说明

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

请求示例

curl --location --request POST 'http://172.16.46.132:8090/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`	交易发起时间
`externalAdditionalData`	`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"
    }
}

退款

接口: `/refund`

请求参数说明

参数名	类型	是否必填	描述
`originalTransactionNo`	`String`	是	原交易流水号
`merchantSerialNo`	`String`	是	商户流水号（需保证全局唯一性）
`refundOrderAmount`	`String`	是	退款金额（最小值为0.01，单位：元，两位小数）
`refundTipAmount`	`String`	否	退款小费金额（最小值为0.01，单位：元，两位小数）
`externalAdditionalData`	`String`	否	附加信息

请求示例

curl --location -g --request POST 'http://192.168.22.57:8090/refund?requestId=12d6156a9a-3440-4d48-b7cc-622c42d2d8ce&sn=247KCASL1947&originalTransactionNo=TKDA0EA8746E00000773578927882240&merchantSerialNo=9a717c02-e30e-4a72-b778-6b0897b80ab8&refundOrderAmount=0.01&refundTipAmount=0.00&optPwdCheck=0&externalAdditionalData="{\"key1\":\"value1\",\"key2\":\"value2\"}"'

响应参数说明

字段名	类型	字段说明
`transactionNo`	`String`	交易流水号（全局唯一）
`originalTransactionNo`	`String`	原交易流水号
`transactionStatus`	`String`	交易状态，参考附录枚举值
`merchantSerialNo`	`String`	商户交易流水号
`orderNo`	`String`	系统生成的唯一订单号
`refundOrderAmount`	`String`	退款金额
`refundTipAmount`	`String`	退款小费金额
`refundPayerFee`	`String`	交易手续费金额
`externalAdditionalData`	`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",
        "originalTransactionNo": "TK999B0FDEB4000008440092432344048",
        "refundOrderAmount": "1.55",
        "refundTipAmount": "1.55",
        "refundPayerFee": "0.00",
        "transactionStatus": "00",
        "externalAdditionalData": "",
    }
}

交易查询

接口: `/query/transaction`

请求参数说明

参数名	类型	是否必填	描述
`transactionNo`	`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"
    }
}

取消交易

接口：`/cancel/transaction`

请求参数

公共请求参数

请求示例

curl --location --request POST 'http://192.168.22.57:8090/cancel/transaction'

响应参数说明

公共返回参数

示例

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

接口介绍​

请求方式​

公共请求参数信息​

公共响应参数信息​

公共响应结构​

响应码定义表​

接口列表​

查询签到信息​

接口：/query/device/status​

响应参数​

签到​

接口：/sign​

请求示例​

响应参数​

消费​

接口: /sale​

参数说明​

请求示例​

响应参数​

撤销​

接口: /revoke​

请求参数说明​

请求示例​

响应参数​

退款​

接口: /refund​

请求参数说明​

请求示例​

响应参数说明​

交易查询​

接口: /query/transaction​

请求参数说明​

请求示例​

响应参数说明​

取消交易​

接口：/cancel/transaction​

请求参数​

请求示例​

响应参数说明​

接口介绍

请求方式

公共请求参数信息

公共响应参数信息

公共响应结构

响应码定义表

接口列表

查询签到信息

接口：`/query/device/status`

响应参数

签到

接口：`/sign`

请求示例

响应参数

消费

接口: `/sale`

参数说明

请求示例

响应参数

撤销

接口: `/revoke`

请求参数说明

请求示例

响应参数

退款

接口: `/refund`

请求参数说明

请求示例

响应参数说明

交易查询

接口: `/query/transaction`

请求参数说明

请求示例

响应参数说明

取消交易

接口：`/cancel/transaction`

请求参数

请求示例

响应参数说明