跳到主要内容
版本:1.1.1

SasS 无人自助售货柜交易接口

1. 简介

提供Server To Server无人自助售货柜交易接口 给服务商(下述描述机构均为服务商) 调用。

注:涉及金额字段,单位均为元

请求地址,请求头信息参看文档: saas公共请求及响应参数-3. 请求公共参数信息

响应头信息参看文档: saas公共请求及响应参数-4. 响应公共参数信息

2.查询接口

2.1 交易查询

介绍:依据商户号以及交易流水号或商户交易流水号(二选一)查询交易信息。

接口地址: /saas/query

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:transaction
businessTypeString业务类型填写:query
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchant
字段名类型是否必传字段名称说明
merchantNoString商户号
Object商户对象信息
transaction
字段名类型是否必传字段名称说明
transactionNoString选填交易流水号与商户交易流水号二选一
merchantSerialNoString选填商户交易流水号与交易流水号二选一
Object交易对象信息
Curl请求示例
curl --location '${PAYMENT_DOMAIN}/saas/query' \
--header 'businessType: query' \
--header 'interfaceName: transaction' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signature: A18VnjMNpXcsW41XDAlkzCXT16V+tNTVdD5/Kp/BHwgJnSHCN6rzaBh9hfm8xQFNNdp0ueb79plOaVzibF5ZLbx7Vy/qYr5iRNq1DZCyHB9XjBRGabLbKfZ/3kRvOrcgRFKy2ZRcAqJVw2J5DryqYTBlYzJZKpq8BbpWzepd/AqsjLSVHGyUJgaDeGeUM1lX52ovJRvSDEt6sTjZt56mOB5Zi+kI3KwawivRe2rdenDDC5LLyJde8+91XCC+hXn+wjXq8eMQJ6n4Wdkyh9Da5j0uwjvTxB6GHAXmWn49dFdSPVOWxjlz33gc2xi7w/oQbecpRrF98Xf52H95QIBwfQ==' \
--header 'signMethod: RSA-SHA256' \
--header 'Content-Type: application/json' \
--data '{
"requestId": "S**************_20250721071251671_06",
"requestTime": "2025-07-21T07:12:51.671+08:00",
"nonceStr": "VTCG6QAxj3YzWwzvuYxIRRNODmk7nTfh",
"data": {
"merchant": {
"merchantNo": "**********"
},
"transaction": {
"transactionNo": "TKE18DD7B12000000843982354104320",
"merchantSerialNo": "MERCHANT_SERIAL_20260128145822"
}
}
}'

响应参数

字段名类型是否必传字段名称说明
transaction
字段名类型是否必传字段名称说明
transactionNoString交易流水号
originalTransactionNoString原交易流水号
orderNoString订单号
amountdecimal支付金额单位:元
addAmountdecimal预授权追加金额单位:元
authorizeAmountdecimal预授权金额单位:元
refundAmountdecimal退款金额单位:元
currencyString币种
statusString交易状态参考 附录-枚举字典 11 交易状态
transactionTypeString交易类型参考 附录-枚举字典 3 交易类型
paymentWayString支付方式参考 附录-枚举字典 5 支付方式
paymentTypeString支付类型参考 附录-枚举字典 6 支付类型
paymentSubtypeString支付子类型参考 附录-枚举字典 7 支付子类型
cardTypeString卡类型参考 附录-枚举字典 8 卡类型
cardFlagString卡标识参考 附录-枚举字典 9 卡标识
cardBrandString卡组织参考 附录-枚举字典 10 卡组织
cardNoDigestString卡号密文摘要根据机构敏感信息配置条件返回,配置允许返回该字段存在值
payerFeedecimal付款方费用交易手续费明确才返回,单位:元
payerRefundFeedecimal付款方退款费用交易手续费明确才返回,单位:元
authCodeString授权码
refundFlagString退款标识00.未处理,01.部分退款,02.全部退款
revokeFlagString撤销标识00.未处理,01.已撤销
authCompleteFlagString完成标识00.未处理,01.已完成
responseCodeString主码
responseMessageString主码说明
subCodeString子码
subMessageString子码说明
completionTimetimestamp交易完成时间
transactionTimetimestamp交易时间
transactionZoneUTCTimetimestamp交易时区时间
transactionZoneIdString时区交易时区 例:Asia/Shanghai
timeZoneFlagInteger时区标识时区标识:0.标准时间,1.夏令时
externalAdditionalDataString外部附加数据返回业务方自定义交易参数原值,JSON格式
Object交易对象

响应Headers数据示例:

signature: bka/ln9zgHTen4jblFP84UJPs2a/paEFbeV/+1cMoW8B5pGegHSGc4dZIxh4bD1oOV0W0lwqCnhSPzbvN9Xb2XGSAREK4WsSk4QrV5axK7Eh6gVtK7TOibtM3KnoA77B6iww3R1uuEclWgrvXcwVqDJpNQbm10sJU6OSHY5Q3UlTRr1t+f5+T1lKHjg0w9VY9VBK61Mwzhc+qrySLVD/WnxVVIO95SfA7wkvhRM8L1i/4OWAonSWo0Xmt/l4ALCHPKr0H/splrvPj1tfq6S3ibg8+PhSIt+B5Mtdb6tlx80BdlXD+Wx2swZ5B70kk83dF/KQvsGT6g10PiGCAN6fSw==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2026-01-28T06:58:23.790+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"transaction": {
"transactionNo": "TKE18DD7B12000000843982354104320",
"orderNo": "10820250722000011211",
"amount": 20.00,
"refundAmount": 10.00,
"payerFee": 0.00,
"payerRefundFee": 0.00,
"payeeFee": 0.00,
"payeeRefundFee": 0.00,
"tipAmount": 0.00,
"currency": "HKD",
"transactionType": "01",
"paymentWay": "01",
"authCode": "467309",
"status": "00",
"responseCode": "200",
"transactionTime": "2025-07-22T04:48:01.000+00:00",
"transactionZoneUTCTime": "2025-07-22T12:48:01.000+08:00",
"transactionZoneId": "Asia/Hong_Kong",
"timeZoneFlag": 0,
"completionTime": "2025-07-22T04:48:02.000+00:00",
"refundFlag": "01",
"revokeFlag": "00",
"authCompleteFlag": "00",
"paymentType": "01",
"paymentSubtype": "03",
"cardFlag": "03",
"cardBrand": "01",
"cardNoDigest": "997a14df7b9a13a216e2e9f2095f9288569847a732b6403378aee27a524a8d9f",
"purseOrderNo": "BANKORDERNO20250910",
"channelTransactionNo": "2025072211287100",
"cardNoMask": "451461******7853"
}
}
}

3.交易接口

3.1 预授权完成

介绍:预授权交易成功后发起预授权完成交易,该接口仅发起预授权完成受理,实际预授权完成状态以异步通知接口为准,参考:4.交易通知

接口地址: /saas/pos

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:auth/capture
businessTypeString业务类型填写:pos
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchant
字段名类型是否必传字段名称说明
merchantNoString商户号
Object商户对象信息
transaction
字段名类型是否必传字段名称说明
transactionNoString原交易流水号
merchantSerialNoString商户交易流水号
amountString金额单位:元
externalAdditionalDataString外部附加数据传入业务方自定义交易参数,JSON格式
Object订单对象信息
Curl请求示例
curl --location '${PAYMENT_DOMAIN}/saas/pos' \
--header 'businessType: pos' \
--header 'interfaceName: auth/capture' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signature: T8KDHqYf8cbK4FtwdD1I0DaQaVACIOCBPvy5kIcSlUhMZRG6fXVBhzz47DIjPOP9NLOKo1i7EsnKcXDaL4pmI3yyTYRMYuPalUp4DH6Pyypvyli4mVHDjw7zZE2lcPOYJO8DG1werdUcrQJ93inLzaeqI2mgAAdjBC+J5Wxva/pooQStuWxm4YRfcYdsTWTfT2Cl+bL3c0yMHwkCKi+Xe0eD7De2SNigxX+9oBzojAoJB0UhpjB3GF4Zy7qQP3kMuCOfZJU5i5XAMcVBBOl27ADxcIU2EAwLliKEpzQw3SbgrUULZTO8Mlh/oQcJLx3WN/uvwYMOFQ1yjY8u16KNtg==' \
--header 'signMethod: RSA-SHA256' \
--header 'Content-Type: application/json' \
--data '{
"requestId": "S**************_20250722042604854_8d",
"requestTime": "2025-07-22T04:26:04.854+08:00",
"nonceStr": "dwq6VXHzTqcqa2wzla779rDCebnzAJTB",
"data": {
"merchant": {
"merchantNo": "**********"
},
"transaction": {
"transactionNo": "TKB7C32E377400000843840740835328",
"merchantSerialNo": "MERCHANT_SERIAL_20250722122604",
"amount": "10",
"tipAmount": "0.00"
}
}
}'

响应参数

字段名类型是否必传字段名称说明
transaction
字段名类型是否必传字段名称说明
merchantSerialNoString商户交易流水号
merchantNoString商户编号
terminalSerialNoString终端序列号
amountString金额单位:元
transactionTypeString交易类型参考 附录-枚举字典 3 交易类型
statusString交易状态参考 附录-枚举字典 11 交易状态
externalAdditionalDataString外部附加数据返回业务方自定义交易参数原值,JSON格式
Object交易对象

响应Headers数据示例:

signature: idCYp8R2h4TPiLLN+E+K3F9uKwScaJjlAUwxut8PwEh4EfHn526IPZuw1MITfEmsQA06sNYrr5hI7dsaBJrBWLV8UFWKfuSkg2aPn94THa3TD/NZt5r7NxGYVAT2IGmw2q+h+z5hFQSBRENsz1r1GIhtQogaH2klN5m5XQNgJlHuGoMNpbCY8MRtDhVjmILrXHb1SrqsMQKW74r4EbjwXi6ZTV4c/OnYIXemg6us8v3kw9h4pKKWPsZh+jP9Y7Xk51SUFxOemxMayrW1xoDuOzZt0W5jCaX07KDrn4CKkFx0IPCnxjiv5vfavONN3/kbt0BYzqLMnFzWTVgIoCWN0w==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2025-07-22T04:27:17.961+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"transaction": {
"merchantNo": "**********",
"terminalSerialNo": "SI********",
"merchantSerialNo": "MERCHANT_SERIAL_20250722122604",
"amount": 10.00,
"transactionNo": "TKD8A489C4F400000843961915965440",
"originalTransactionNo": "TKB7C32E377400000843840740835328",
"orderNo": "10820250722000011204",
"refundAmount": 0.00,
"tipAmount": 0.00,
"currency": "HKD",
"transactionType": "06",
"paymentWay": "01",
"authCode": "288927",
"status": "00",
"responseCode": "200",
"transactionTime": "2025-07-22T04:27:14.000+00:00",
"transactionZoneUTCTime": "2025-07-22T12:27:14.000+08:00",
"transactionZoneId": "Asia/Hong_Kong",
"timeZoneFlag": 0,
"completionTime": "2025-07-22T04:27:18.000+00:00",
"cardBrand": "01"
}
}
}

3.2 预授权撤销

介绍:预授权交易成功后可发起预授权撤销交易,该接口仅发起预授权撤销受理,实际预授权撤销状态以异步通知接口为准,参考:4.交易通知

接口地址: /saas/pos

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:auth/revoke
businessTypeString业务类型填写:pos
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchant
字段名类型是否必传字段名称说明
merchantNoString商户号
Object商户对象信息
transaction
字段名类型是否必传字段名称说明
transactionNoString原交易流水号
merchantSerialNoString商户交易流水号
externalAdditionalDataString外部附加数据传入业务方自定义交易参数,JSON格式
Object订单对象信息
Curl请求示例
curl --location '${PAYMENT_DOMAIN}/saas/pos' \
--header 'businessType: pos' \
--header 'interfaceName: auth/revoke' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signature: DB07yd0mkHAyDG+m6d51Y6ju0TPuvvvJqHFahJ3U3uRE0qYfG7Q4BarFMUk9iBdzALurXPR66hUulixLjpoKAbuABnDKTPPP1okyE0tr+y3Xak8AuLQ0blGJJeSxN1+vhq8pCnU601OgVYDs/s2UDceSki1cVKBE/9gwVDQ6GFh2Cu1t3uj1xEZLiriWj3Ps2wxsw7vHiVmrN7dIH33YnOn4Xn79j4jYk5869JUbpm2uPRCg1bHU4+4Yk1EUDtI4TDmzNWP5RBahcKN0X4yTRY/bvT0kD4NwVijqB/xi7EdMzGRNaR7/FpbBeI7kXscpIXxjxbUaPOpL5qQctbMBGg==' \
--header 'signMethod: RSA-SHA256' \
--header 'Content-Type: application/json' \
--data '{
"requestId": "S**************_20250722043718741_a9",
"requestTime": "2025-07-22T04:37:18.741+08:00",
"nonceStr": "qK761D4PPNrXfPKy3wrMPV20x86yVzTh",
"data": {
"merchant": {
"merchantNo": "**********"
},
"transaction": {
"transactionNo": "TK7AE428D09800000843971106439168",
"merchantSerialNo": "MERCHANT_SERIAL_20250722123718"
}
}
}'

响应参数

字段名类型是否必传字段名称说明
transaction
字段名类型是否必传字段名称说明
merchantSerialNoString商户交易流水号
merchantNoString商户编号
terminalSerialNoString终端序列号
amountString金额单位:元
transactionTypeString交易类型参考 附录-枚举字典 3 交易类型
statusString交易状态参考 附录-枚举字典 11 交易状态
externalAdditionalDataString外部附加数据返回业务方自定义交易参数原值,JSON格式
Object交易对象

响应Headers数据示例:

signature: Oil2Qv4rKWTwlDwVA39b4mGqRX8kBY3kWtJhUHQnrGvDR48Q8h/0VuQYkp+tz0q28XPKftUG8XUf4lkcGRkEfTn/E2P6pV7HeVvmLzMkpp2na8NnViflTWZCf9jF0xZI6cLXCdd8cJZZKhJkxbGp6l6V3cxU6Dl/pCSVNM2Ys9q618516Ynd4mGI4KPW/pmsLJiGuWFT8M8LwEZEM4ZkM+EofXDWVCoNjhMiIZeCdN0V49plKJfkmJYKM5n3IAZ1BwMiivM6FQygF5/MtgZ5MlEq+qFTw/13EVYC9X2PuwRi/BKyItHQanCP4LuCzM9Pnl/4KLJ3HG2Z675qjqreIA==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2025-07-22T04:37:47.920+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"transaction": {
"merchantNo": "**********",
"terminalSerialNo": "SI********",
"merchantSerialNo": "MERCHANT_SERIAL_20250722123718",
"amount": 20.00,
"transactionNo": "TKCB0FB454BF00000843972268752896",
"originalTransactionNo": "TK7AE428D09800000843971106439168",
"orderNo": "10820250722000011206",
"refundAmount": 0.00,
"tipAmount": 0.00,
"currency": "HKD",
"transactionType": "05",
"paymentWay": "01",
"authCode": "409703",
"status": "00",
"responseCode": "200",
"transactionTime": "2025-07-22T04:37:46.000+00:00",
"transactionZoneUTCTime": "2025-07-22T12:37:46.000+08:00",
"transactionZoneId": "Asia/Hong_Kong",
"timeZoneFlag": 0,
"completionTime": "2025-07-22T04:37:48.000+00:00",
"cardBrand": "01"
}
}
}

3.4 退款

介绍:用于处理交易退款请求,支持部分退款,和全额退款,该接口仅发起退款受理,实际预授权完成状态以异步通知接口为准,参考:4.交易通知

接口地址: /saas/pos

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:refund
businessTypeString业务类型填写:pos
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchant
字段名类型是否必传字段名称说明
merchantNoString商户号
Object商户对象信息
transaction
字段名类型是否必传字段名称说明
transactionNoString原交易流水号
merchantSerialNoString商户交易流水号
amountString金额单位:元
externalAdditionalDataString外部附加数据传入业务方自定义交易参数,JSON格式
Object订单对象信息
Curl请求示例
curl --location '${PAYMENT_DOMAIN}/saas/pos' \
--header 'businessType: pos' \
--header 'interfaceName: refund' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signature: WYFGBpvVS9XabLuXNZjL60FCku80N3+dvZi08WNb7vowLgQbZeYCVdih0Zgu96vu5+C4Xr6Ycr2eNyBhUhGIlSjXR7/qJvjRpcm0o8+cPwvD+i+MGktbtCFiN131k2FHs0+wkdrdZDD6VG1aYkZlVtnzzWkPRIDDdgbD5wrctM4gs/Pqb4LjfDDNf9VmdciEDAxXFGOAsyZAC8nkH/DckVtAWnWC9gzhfS3KGAX/xVyitisFozScb7Hdbewh4Rv8IBiIiHIk5GGPbxnFjkgzKf3TpOJMgL1845Tx3geBw0T5NuJSs2Et/NW0Y+Pp1FkaiWR5xTRRp3QcP2FNWyPpsQ==' \
--header 'signMethod: RSA-SHA256' \
--header 'Content-Type: application/json' \
--data '{
"requestId": "S**************_20250722045241825_fc",
"requestTime": "2025-07-22T04:52:41.825+08:00",
"nonceStr": "aEJ6mdknJnDSQLeu0iyDyueMI7upoiUB",
"data": {
"merchant": {
"merchantNo": "**********"
},
"transaction": {
"transactionNo": "TKE18DD7B12000000843982354104320",
"merchantSerialNo": "MERCHANT_SERIAL_20250722125241",
"amount": "10.00",
"tipAmount": "0.00"
}
}
}'

响应参数

字段名类型是否必传字段名称说明
transaction
字段名类型是否必传字段名称说明
merchantNoString商户编号
terminalSerialNoString终端序列号
merchantSerialNoString商户交易流水号
amountdecimal支付金额单位:元
transactionNoString交易流水号
originalTransactionNoString原交易流水号
currencyString币种
statusString交易状态参考 附录-枚举字典 11 交易状态
orderNoString订单号
externalOrderNoString外部订单号
refundAmountdecimal退款金额单位:元
transactionTypeString交易类型参考 附录-枚举字典 3 交易类型
paymentWayString支付方式参考 附录-枚举字典 5 支付方式
authCodeString授权码
responseCodeString主码
responseMessageString主码说明
subCodeString子码
subMessageString子码说明
completionTimetimestamp交易完成时间
transactionTimetimestamp交易时间
transactionZoneUTCTimetimestamp交易时区时间
transactionZoneIdString时区交易时区 例:Asia/Shanghai
timeZoneFlagInteger时区标识时区标识:0.标准时间,1.夏令时
externalAdditionalDataString外部附加数据返回业务方自定义交易参数原值,JSON格式
Object交易对象

响应Headers数据示例:

signature: kNG/8hcqaVIzeqhufxpI7P1phMaDyipFmi7hjp1E/dRI/YxxJuE67t7YfLcD+Nvour2UyexsvtGCefAXuVZgQnHDGCr7XHmJDzkuxe1YD6KI6O8ILgF3FOqawZKBUkCQGl/XwYscuTWeJVh4PD0oRf3LDiAmaNG/V2t+r5a308/usJOzK45Zf/dHfxylXKCindvQ7OAVSmvSElB0o7s0gh5DsYLzy1ZOI9BdVlIWHOGUiJYZlmV+8hF5zhGrOplGZTCDedIhQQO+g/whqpZv0icmTWcfHyyF9S6mOaPV87V+xCVR1e0JBdix7F8Arn0I8wmveYW0EPDLakhh/M9kAQ==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2025-07-22T04:52:56.139+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"transaction": {
"merchantNo": "**********",
"terminalSerialNo": "SI********",
"merchantSerialNo": "MERCHANT_SERIAL_20250722125241",
"amount": 10.00,
"transactionNo": "TK0262FCA3DB00000843987140689920",
"originalTransactionNo": "TKE18DD7B12000000843982354104320",
"orderNo": "10820250722000011211",
"refundAmount": 0.00,
"tipAmount": 0.00,
"currency": "HKD",
"transactionType": "08",
"paymentWay": "01",
"status": "00",
"responseCode": "200",
"transactionTime": "2025-07-22T04:52:54.000+00:00",
"transactionZoneUTCTime": "2025-07-22T12:52:54.000+08:00",
"transactionZoneId": "Asia/Hong_Kong",
"timeZoneFlag": 0,
"completionTime": "2025-07-22T04:52:56.000+00:00",
"cardBrand": "01"
}
}
}

3.5 预授权追加

介绍:用于处理最终预授权完成金额超额场景下,先请求预授权追加接口,该接口仅发起预授权完成受理,实际预授权完成状态以异步通知接口为准,参考:4.交易通知

接口地址: /saas/pos

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:auth/add
businessTypeString业务类型填写:pos
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchant
字段名类型是否必传字段名称说明
merchantNoString商户号
Object商户对象信息
transaction
字段名类型是否必传字段名称说明
transactionNoString原交易流水号
merchantSerialNoString商户交易流水号
amountString金额单位:元
externalAdditionalDataString外部附加数据传入业务方自定义交易参数,JSON格式
Object订单对象信息
Curl请求示例
curl --location '${PAYMENT_DOMAIN}/saas/pos' \
--header 'businessType: pos' \
--header 'interfaceName: auth/add' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signature: WJ+pnhryqh0f0BswcFmPI93yrAGFGQ4BdrvFH4zvImv+eFyHhve1bNYWe8FU5TsxqqqzcZoS9z1MSVxqlsG/9/7tU3n+I2L5ij2GBZRBKS48ruUw8dMVKjhe+KElGm+QLCC2TXykFBqT+x7YrxoDTOpyESsJLLfbgjZXRNJNALBkdWcjHTMZi11s2R3nHxkbPKndbX0FperpwOD0Gt+xjXC9wKddBnmyAhteTbYMQPYAU0wW5PYATkPOTnKT8dCg/l7SM+F9f93IKlslIVtdMVLuUfHhnkzfgIO5e8egmHwl8KY8VAcIi4Ylqn3EzVJHC4nCMgxcNLtcCe27+yLsCQ==' \
--header 'signMethod: RSA-SHA256' \
--header 'Content-Type: application/json' \
--data '{
"requestId": "S**************_20250722114523648_0a",
"requestTime": "2025-07-22T11:45:23.648+08:00",
"nonceStr": "5c6CZnEWSbCggu49UaetKgeO4e3N4SF2",
"data": {
"merchant": {
"merchantNo": "**********"
},
"transaction": {
"transactionNo": "TK5157ACFC2C00000843976814936064",
"merchantSerialNo": "MERCHANT_SERIAL_20250722194523",
"amount": "10"
}
}
}'

响应参数

字段名类型是否必传字段名称说明
transaction
字段名类型是否必传字段名称说明
merchantSerialNoString商户流水号
merchantNoString商户编号
terminalSerialNoStringString终端序列号
amountdecimal金额单位:元
transactionTypeString交易类型参考 附录-枚举字典 3 交易类型
statusString交易状态参考 附录-枚举字典 11 交易状态
externalAdditionalDataString外部附加数据返回业务方自定义交易参数原值,JSON格式
Object交易对象

响应Headers数据示例:

signature: phdKQ6eySKqloGtOvu9vOO4coQUzdimMKLl9BH433Gh0VlLWiF98c6jAY50EHvD+4vjIk/31sTKzK74EHrbc/Xr9AslJ8KgLu+bx4oZKqAla8dE+wzCdkwXR9nq5EffUY6u/bxIYCjK93NMsHOFxrWrTYgMaolWYOCYWxRBNHAK2TnxUHg0hSNybiRwvv5Ouw8y+RFn0f2OO5eQoyJzRzaza13jUmWr5K3qQzgRQUYH5iiolwAHNAf11aoGkgiHdkEfQ5dPfH0en/TGOEh8PKqMsdz4SoNS4/JcC/j5KLniKiFQucyYVxdD0iB+pnFZygx3rtgltZoBdk9zfXZ3nhA==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2025-07-22T11:45:28.840+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"transaction": {
"merchantNo": "**********",
"terminalSerialNo": "SI********",
"merchantSerialNo": "MERCHANT_SERIAL_20250722194523",
"amount": 10,
"transactionType": "04",
"status": "11"
}
}
}

4.交易通知

4.1交易回调业务方

介绍:相关交易逻辑完成后给业务方推送最终交易结果通知。

通知参数

字段名类型是否必传字段名称说明
transaction
字段名类型是否必传字段名称说明
terminalSerialNoString终端序列号
merchantNoString商户号
transactionNoString交易流水号
originalTransactionNoString原交易流水号
merchantSerialNoString商户交易流水号
amountdecimal支付金额单位:元
currencyString币种
statusString交易状态参考 附录-枚举字典 11 交易状态
orderNoString订单号
externalOrderNoString外部订单号
refundAmountdecimal退款金额单位:元
transactionTypeString交易类型参考 附录-枚举字典 3 交易类型
paymentWayString支付方式参考 附录-枚举字典 5 支付方式
cardNoDigestString卡号密文摘要根据机构敏感信息配置条件返回,配置允许返回该字段存在值
authCodeString授权码
responseCodeString主码
responseMessageString主码说明
subCodeString子码
subMessageString子码说明
completionTimetimestamp交易完成时间
transactionTimetimestamp交易时间
transactionZoneUTCTimetimestamp交易时区时间
transactionZoneIdString时区交易时区 例:Asia/Shanghai
timeZoneFlagInteger时区标识时区标识:0.标准时间,1.夏令时
externalAdditionalDataString外部附加数据返回业务方自定义交易参数原值,JSON格式
Object交易对象
Curl请求示例
curl --location '${SERVICE_NOTIFY_URL}' \
--header 'Content-Type: application/json' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signMethod: RSA-SHA256' \
--header 'signature: gmEnbXHetb0a+iwz2xJwgYXKHHwYd9Yy8fumDlzOevruscS6yawHjgxZGDhW24+hrJDIS2vwDF879dUOk/YL3kGvoUHXe52UM0y/81+JJ9PD2Ic0C8agBOmSXEiG9ROfOjRDmfxz/zYOHhWGBuN7VtNlKxUxopw8l57MR1ouSLt+g3XEEqpNTqMhB3njTZ5CXZ/XZj95dfZUkkXtXdC1mPOtSkE55gNxTSECcfKDT78gmBMcJEgBpZHoaStEt+KEe6TZ7avmBpP43pccKALWDDkjmiCdXqDxl9a3HOpWj5bx9RALg6GuCDheNBBy/D0CRsQeBEljmBKmHTr1/IVbkQ==' \
--data '{
"requestId": null,
"requestTime": null,
"responseTime": "2025-07-18T10:44:18.866+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"transaction": {
"merchantNo": "**********",
"terminalSerialNo": "SI********",
"merchantSerialNo": "2025071818435461",
"amount": 6.00,
"transactionNo": "TK523BE28B8300000808914719686656",
"originalTransactionNo": "TK9B637B1A5D00000808914329124864",
"orderNo": "10820250718000011158",
"refundAmount": 0.00,
"tipAmount": 0.00,
"currency": "HKD",
"transactionType": "06",
"paymentWay": "01",
"authCode": "657666",
"status": "00",
"responseCode": "200",
"transactionTime": "2025-07-18T10:44:17.000+00:00",
"transactionZoneId": "Asia/Hong_Kong",
"timeZoneFlag": 0,
"completionTime": "2025-07-18T10:44:19.000+00:00",
"cardNoDigest": "fdaec090552b92671fe93ad58ae46de41e33e3d7c211bf88f43e82bac4d05676",
"cardBrand": "01"
}
}
}'

5.管理类接口

5.1 终端操作状态处理

介绍:更改或查询设备当前支付可受理状态。

接口地址: /saas/query

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:paymentStatus
businessTypeString业务类型填写:query
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchant
字段名类型是否必传字段名称说明
merchantNoString商户号
Object商户对象信息
terminal
字段名类型是否必传字段名称说明
snString终端序列号
paymentStatusString选填终端支付操作状态00 未操作(可受理新支付订单),01 操作中( 不可受理新支付订单,更改时可传对应值
Object终端信息
Curl请求示例
curl --location '${PAYMENT_DOMAIN}/saas/query' \
--header 'businessType: query' \
--header 'interfaceName: paymentStatus' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signature: KbTF+Rs5YagWBne8abUaU3EpRB1DCvnySUah/wRqFAFguf7+nA5DAMm9mG9/bsrVTZnLyBwCREFsqGIAPnK4FhB6WVsm0182Ge4C6HvdGD10kp+InylWbIZXxU6Q/6QxOJmrd8xc5LOlvhhlHksx1F/twFT0VHqvoPHHlyVBfOdmi6rh/GjbWy62twyA4EwPEJhjog/2tMm2YZNjuYIRF/01dLvPwizgyWKMxAYKTKDTIeoIeeD1qZ9a4qx3+RBjWN6jl1ZniFQ3kOqaJbear7MCgHzgiA/qoD94FC4Eb8MZ6NAsh+U6dI8sPGT1RKwbA6DiHaMsFkFyrfRu0K1URQ==' \
--header 'signMethod: RSA-SHA256' \
--header 'Content-Type: application/json' \
--data '{
"requestId": "S**************_20250723043936092_8f",
"requestTime": "2025-07-23T04:39:36.092+08:00",
"nonceStr": "QLAOcvJj0ojzOWg5YQLGjfJtF43ncsz2",
"data": {
"merchant": {
"merchantNo": "**********"
},
"terminal": {
"sn": "SI********",
"paymentStatus": "00"
}
}
}'

响应参数

字段名类型是否必传字段名称说明
merchant
字段名类型是否必传字段名称说明
merchantNoString商户号
Object交易对象
terminal
字段名类型是否必传字段名称说明
snString终端序列号
paymentStatusString终端支付操作状态00 未操作(可受理新支付订单),01 操作中( 不可受理新支付订单
Object终端信息

响应Headers数据示例:

signature: qpmtmNE9I9kqBEmPl4a2XwWCE23pJ9l9E9w8sqtm8fPRMIZLihg9UoF7CP+qX99P15F9pZM9diN545v8LzoT1OGr6EL1zciOQJu0361tED+B7PQi9sEXkBrn70sqvFgolYzi5gcxNC9j6usjg2s2KwWMJIjIjJNnZ/YNTfxXMf8T9C+66osQKF9XdEtn5GBwvc2JzLy6Fb34Heo4/TpHAFxATtsOpRJCz2/aqtSjf2SUHYbWxBFtkKgj6BdQIKCX8Zl36DvSHHyASOc/ae5wMLPv9KVsB4ZRM5T40geaxVNQiS6lxLgKZ3LDKukx155W1gXd9kJwwlyXy48Ctg7fxQ==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2025-07-23T04:39:49.626+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"merchant": {
"merchantNo": "**********",
"zoneId": null,
"channelCode": null,
"channelMerchantNo": null,
"productNo": null
},
"terminal": {
"sn": "SI********",
"paymentStatus": "00"
}
}
}

5.2 设备业务参数查询

介绍:设备业务参数查询。

接口地址: /saas/manage

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:posParam/query
businessTypeString业务类型填写:manage
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchantNoString商户号
terminalSerialNoString终端序列号
Curl请求示例
curl --location --request POST '${PAYMENT_DOMAIN}/saas/manage' \
--header 'businessType: manage' \
--header 'interfaceName: posParam/query' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signature: M1kcxyQX1vdwl/15Dp3mBWrczeyi9u8F3nQ1Vszyz2r0jLc5i8Xcbe6+Bo+8theVjZbVdLwvDHUuy6HbHimwQgdg0Zz2c/M5dkPRcbT7iQ2fjq08a0V4fbbMEK3znyd/Bi1uvzL8VNGpMY+46PfFBavGIX/LkZtmfbU+6GXOUQwgH5Q6KM16T4vWx1ps0YQSvj4x9BNwjTjCghLokFXVbt+zZQLunVSBrDMiYuJiyxgIU39WgTcmUQxGi1qvJuteMPIXbkrFDiVq/22ccSsR/y5C5sxldS0KiKk94QtB3yPzaU3i9GWgG5aeBFNvPGZcsVxozk4+KuIXp5zxNXS11g==' \
--header 'signMethod: RSA-SHA256' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
"requestId": "S**********_20250821035014868_e4",
"requestTime": "2025-08-21T03:50:14.868+08:00",
"nonceStr": "IzZHRhB22rlNaK73ZSYeUyNDKWwvD3f1",
"data":{
"merchantNo":"********",
"terminalSerialNo":"SN*******"
}
}'

响应参数

字段名类型是否必传字段名称说明
merchantNoString商户号
terminalSerialNoString终端序列号(sn)
showCardButtonint设备读卡按钮0 不展示,1 展示
defaultAuthorizeAmountnumber默认预授权金额单位:元
h5UrlString首页嵌入h5地址h5Status = '01'才会生效
h5StatusString首页嵌入h5开关状态00 停用(终端不显示),01 启用( 终端显示 )

响应Headers数据示例:

signature: qpmtmNE9I9kqBEmPl4a2XwWCE23pJ9l9E9w8sqtm8fPRMIZLihg9UoF7CP+qX99P15F9pZM9diN545v8LzoT1OGr6EL1zciOQJu0361tED+B7PQi9sEXkBrn70sqvFgolYzi5gcxNC9j6usjg2s2KwWMJIjIjJNnZ/YNTfxXMf8T9C+66osQKF9XdEtn5GBwvc2JzLy6Fb34Heo4/TpHAFxATtsOpRJCz2/aqtSjf2SUHYbWxBFtkKgj6BdQIKCX8Zl36DvSHHyASOc/ae5wMLPv9KVsB4ZRM5T40geaxVNQiS6lxLgKZ3LDKukx155W1gXd9kJwwlyXy48Ctg7fxQ==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2025-08-21T03:50:15.745+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"merchantNo": "********",
"terminalSerialNo": "********",
"showCardButton": 1,
"defaultAuthorizeAmount": 1.01,
"h5Url": null,
"h5Status": "00"
}
}

5.3 设备业务参数修改

介绍:设备业务参数修改。

接口地址: /saas/manage

Header 参数

字段名类型是否必传字段名称说明
interfaceVersionString版本号默认值:1.0.0
languageString语言语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceNameString接口名称填写:posParam/update
businessTypeString业务类型填写:manage
orgNoString机构编号
orgCertIdString机构密钥证书序列号
signatureString机构签名
signMethodString机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名类型是否必传字段名称说明
merchantNoString商户号
terminalSerialNoString终端序列号(sn)key = merchantNo + terminalSerialNo,以下相关配置项不传或者传null则表示不更新该字段
showCardButtonint设备读卡按钮0 不展示,1 展示
defaultAuthorizeAmountnumber默认预授权金额小数位保留两位,单位:元
h5UrlString首页嵌入h5地址h5Status = '01'才会生效
h5StatusString首页嵌入h5开关状态00 停用(终端不显示),01 启用( 终端显示 )
Curl请求示例
curl --location --request POST '${PAYMENT_DOMAIN}/saas/manage' \
--header 'businessType: manage' \
--header 'interfaceName: posParam/update' \
--header 'interfaceVersion: 1.0.0' \
--header 'language: zh_CN' \
--header 'orgNo: S*************' \
--header 'orgCertId: ***********************' \
--header 'signature: HXNBfq8M70LQr1Gyl043fLNilQikxGYknEyFCinpchR1XH/rDIoiD7EpJCpNntNRFnTeS8Hxy+mH2v94tNmnhzOKYbYzlMz+QqGOtqKURqL5bmraWhg63H6m5zgKC0coIpFB3mSrav+0ZqW5bQdu+i4dCrjH5RdMiRZow0dbyz8SKo0PtEVEI5rnVynaPEiNbvW4RgTeG2Hg+2KEFnBs1QASTRhcl8/0hQvy/+PUZ1s+Mg8jq5B9zxLCGl/JIRwArSVqNj2bjNMrwfCVUPKpp0UYPpru+S4FfbElauL7/lq8t87Yg+w8icQyTE54SdxCQJ2x7NCwMB9WqTIw4LVq7A==' \
--header 'signMethod: RSA-SHA256' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
"requestId": "S****************_20250821060413566_09",
"requestTime": "2025-08-21T06:04:13.566+08:00",
"nonceStr": "VBweWqOo2jJjheaZjlxEmkEIiFu4J3am",
"data":{
"merchantNo": "**********",
"terminalSerialNo": "**********",
"showCardButton": 1,
"defaultAuthorizeAmount": 10.00,
"h5Url": null,
"h5Status": "00"
}
}'

响应参数

字段名类型是否必传字段名称说明
merchantNoString商户号
terminalSerialNoString终端序列号(sn)
showCardButtonint设备读卡按钮0 不展示,1 展示
defaultAuthorizeAmountnumber默认预授权金额单位:元
h5UrlString首页嵌入h5地址h5Status = '01'才会生效
h5StatusString首页嵌入h5开关状态00 停用(终端不显示),01 启用( 终端显示 )

响应Headers数据示例:

signature: qpmtmNE9I9kqBEmPl4a2XwWCE23pJ9l9E9w8sqtm8fPRMIZLihg9UoF7CP+qX99P15F9pZM9diN545v8LzoT1OGr6EL1zciOQJu0361tED+B7PQi9sEXkBrn70sqvFgolYzi5gcxNC9j6usjg2s2KwWMJIjIjJNnZ/YNTfxXMf8T9C+66osQKF9XdEtn5GBwvc2JzLy6Fb34Heo4/TpHAFxATtsOpRJCz2/aqtSjf2SUHYbWxBFtkKgj6BdQIKCX8Zl36DvSHHyASOc/ae5wMLPv9KVsB4ZRM5T40geaxVNQiS6lxLgKZ3LDKukx155W1gXd9kJwwlyXy48Ctg7fxQ==
orgCertId: ****************************************
signMethod: RSA-SHA256
响应Body数据示例
{
"requestId": null,
"requestTime": null,
"responseTime": "2025-08-21T06:04:13.107+00:00",
"respCode": 200,
"respMsg": "success",
"busCode": null,
"busMsg": null,
"busSubCode": null,
"busSubMsg": null,
"data": {
"merchantNo": "********",
"terminalSerialNo": "********",
"showCardButton": 1,
"defaultAuthorizeAmount": 10.00,
"h5Url": null,
"h5Status": "00"
}
}