文档目录
AiMT 新加坡
面向新加坡金融机构、独立软件开发商(ISV)及支付服务商的推送支付接入方案。将订单推送至专用支付终端,通过 AiMT 完成支付、退款、查询、结算与撤销等业务操作。
适用范围与能力
适用于新加坡门店收银系统通过 AiMT 将订单推送到已开通的专用支付设备。服务端负责签名、保存订单和确认结果;收银设备负责展示与执行付款。本页覆盖调用链,不代表所有渠道、机型及固件都已开通全部能力。
| 任务 | 接口 | 完成判据与边界 |
|---|---|---|
| 注册调用方 | /terminal/activate | 获得并安全保存 terminal_sn / terminal_key;目标设备另外绑定。 |
| 更新密钥 | /terminal/checkin | 新密钥校验并原子持久化;不替代设备注册。 |
| 收款 | /appPush/tradePush | PUSH_SUCCESS 仅表示受理;查询/验签通知确认原订单已支付。 |
| 查单 | /upay/v2/query | 查询结果中的订单、流水类型、金额、状态一致。 |
| 退款/撤销(设备路径) | /mis/refund | 按设备/渠道约定使用;MIS_PUSH_SUCCESS 不等于资金已退。 |
| 退款(服务端路径) | /upay/v2/refund | 渠道开通并具有退款权限;确认指定 refund_request_no 的结果。两种退款路径按已接入方案选择,结果未知时不能互相兜底重发。 |
| 关单 | /mis/close | 关闭尚未完成支付的订单;处理支付与关单竞争,已支付订单按开通的退款路径处理。 |
| 终端交班 | /mis/shift | 确认设备执行结果;不是资金清算、到账或账单接口。 |
支付方式与环境
pay_type=1 表示银行卡,2 表示扫码,6 表示 C 扫 B(顾客扫描商户收款码);仅选择已为商户和设备开通的值。参考枚举中的 3 是花呗,并非通用分期;4/5 是预授权。这些值的存在不构成新加坡能力承诺,预授权类型不能任意与其他类型混用,部分固件还有 2/6 映射差异。支付品牌、SGD 币种、部分退款、多次退款、撤销和预授权能力均须以开通配置验证。
联调前取得测试地址、测试商户/设备、平台公钥、测试支付介质与渠道能力清单。https://api.aimt-horizon.com 是已提供的新加坡接入域名,不默认代表不会真实扣款的沙箱。生产与测试凭证、公钥和回调配置分开管理。
完成第一笔测试交易
先完成接入准备及调用方激活,再按此路径验证。每次只推送一个新的业务订单;运行 push 会向配置的环境提交真实 API 请求。
- 备齐配置。从安全配置或环境变量读取
AIMT_BASE_URL、AIMT_TERMINAL_SN、AIMT_TERMINAL_KEY、AIMT_TARGET_DEVICE_ID、AIMT_NOTIFY_URL。设置同一商户内唯一的AIMT_ORDER_ID(1~32 位英文/数字)。回调接收端应先按通知规范部署。 - 确认测试范围。核实测试商户、SGD、设备及
pay_type=1,2,6已开通后设置AIMT_TEST_CONFIRMED=1。例子下单金额为"100",即 SGD 1.00;这个开关只是本地防误操作,不能把生产环境变成沙箱。 - 先运行签名自检,再推送一次。Python 3 标准库示例无第三方依赖。自检无需网络。推送预期为
result_code="200"且biz_response.result_code="PUSH_SUCCESS",此时不履约。 - 在指定设备付款。核对设备上的金额与商户订单;保留设备流水,等待服务端通知,并使用相同
AIMT_ORDER_ID执行 query。 - 确认结果。核对
client_sn、金额及PAYMENT / SUCCESS / PAID,持久化sn、tsn。后续可设置AIMT_ORDER_SN优先按平台订单号查询。不明结果按恢复流程处理。 - 验证退款。按已开通的退款路径发起一个新退款业务,记录退款号;设置
AIMT_REFUND_REQUEST_NO后 query 必须定位该次退款。支付与退款各保留独立记录。
python3 aimt_example.py selftest python3 aimt_example.py push python3 aimt_example.py query
Python 3:签名、推单与查单完整示例
通过代码块的下载按钮取得 aimt_example.py。此示例仅覆盖推单/查询的普通响应验签,不覆盖激活、签到或回调接收;这些接口的密钥与验签规则见各自章节。终端异常只打印脱敏标识和状态。
import hashlib
import hmac
import json
import os
import sys
import time
import urllib.error
import urllib.request
from urllib.parse import urlsplit
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
def signature(raw, key):
return hashlib.sha256(raw + key.encode("utf-8")).hexdigest()
def call(base, path, payload, terminal, key):
raw = json.dumps(payload, ensure_ascii=False,
separators=(",", ":")).encode("utf-8")
request = urllib.request.Request(
base + path, data=raw, method="POST",
headers={
"Content-Type": "application/json",
"Authorization-Type": "sha256",
"Authorization": terminal + " " + signature(raw, key),
},
)
opener = urllib.request.build_opener(NoRedirect())
try:
response = opener.open(request, timeout=45)
except urllib.error.HTTPError as error:
response = error
# A timeout raises an exception; never automatically repeat a push.
with response:
response_raw = response.read()
http_status = response.code
auth = response.headers.get("Authorization", "").split(" ")
expected = signature(response_raw, key)
if (len(auth) != 2 or auth[0] != terminal
or not hmac.compare_digest(auth[1].lower(), expected)):
raise RuntimeError("Unverified response; keep outcome unknown")
result = json.loads(response_raw)
if not 200 <= http_status < 300 or result.get("result_code") != "200":
raise RuntimeError(
"API error: " + str(result.get("error_code", http_status))
)
return result
def main():
mode = sys.argv[1] if len(sys.argv) > 1 else "query"
if mode == "selftest":
raw = b'{"terminal_sn":"TEST_TERMINAL","client_sn":"SG_TEST_001"}'
assert signature(raw, "TEST_SECRET") == (
"3425ab126f49ea26ec607af9d2d2c90225db75a43b8fabd01e28580d2080d00f"
)
print("Signature self-test passed (no network request)")
return
if mode not in ("push", "query"):
raise SystemExit("Usage: aimt_example.py selftest|push|query")
base = os.environ["AIMT_BASE_URL"].rstrip("/")
url = urlsplit(base)
if (url.scheme != "https" or not url.netloc or url.username
or url.password or url.path or url.query or url.fragment):
raise SystemExit("AIMT_BASE_URL must be the assigned HTTPS origin")
terminal = os.environ["AIMT_TERMINAL_SN"]
key = os.environ["AIMT_TERMINAL_KEY"]
order = os.environ["AIMT_ORDER_ID"]
if not order.isascii() or not order.isalnum() or len(order) > 32:
raise SystemExit("AIMT_ORDER_ID: 1-32 ASCII letters/digits")
payload = {"terminal_sn": terminal}
if mode == "push":
if os.environ.get("AIMT_TEST_CONFIRMED") != "1":
raise SystemExit("Confirm test environment before setting AIMT_TEST_CONFIRMED=1")
payload.update({
"out_trade_no": order,
"total_amount": "100",
"trade_time": str(int(time.time() * 1000)),
"target_device_id": os.environ["AIMT_TARGET_DEVICE_ID"],
"notify_url": os.environ["AIMT_NOTIFY_URL"],
"pay_type": "1,2,6",
})
path = "/appPush/tradePush"
else:
if os.environ.get("AIMT_ORDER_SN"):
payload["sn"] = os.environ["AIMT_ORDER_SN"]
else:
payload["client_sn"] = order
if os.environ.get("AIMT_REFUND_REQUEST_NO"):
payload["refund_request_no"] = os.environ["AIMT_REFUND_REQUEST_NO"]
path = "/upay/v2/query"
result = call(base, path, payload, terminal, key)
business = result.get("biz_response") or {}
transaction = business.get("data") or {}
# Print only identifiers and states, never full customer payloads.
print(json.dumps({
"result_code": result.get("result_code"),
"biz_result": business.get("result_code"),
"error_code": business.get("error_code"),
**{k: transaction.get(k) for k in
("sn", "client_sn", "tsn", "type", "status",
"order_status", "total_amount", "net_amount")},
}, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
第一次测试的通过标准:商户只产生一笔收款;推单、查单和通知能关联同一订单;通知验签及纯文本应答正确;查询与通知不会导致重复履约。仅看到设备支付成功或 PUSH_SUCCESS 不算通过。
方案概览
五项核心能力,覆盖支付业务全流程
关键术语
| 术语 | 说明 |
|---|---|
| vendor_sn | 服务商序列号,金融机构/ISV 的唯一标识 |
| vendor_key | 服务商密钥,用于激活接口签名 |
| app_id | 应用 ID,用于区分不同业务应用 |
| code | 激活码,由平台按门店与应用发放;有效期、补发和重新激活规则以发放说明为准。 |
| device_id | 调用方设备的稳定唯一标识,用于激活 ISV 收银系统;与接收支付指令的 target_device_id 分开管理。 |
| terminal_sn | 请求中的 terminal_sn 为 API 调用方终端序列号,激活后获得;不是目标设备 TUSN。取消通知中的同名字段可能为目标支付终端号,详见异步回调。 |
| terminal_key | 终端密钥,激活后分配,用于交易接口签名 |
| target_device_id | 目标支付设备 ID,例如设备配置时扫描的 MT919 终端 TUSN 编号 |
| out_trade_no | 商户订单号,同一商户内唯一;对应查询与服务端退款的 client_sn。网络重试不能新建业务订单号。 |
| sn | 系统订单号,由平台分配的全局唯一订单标识 |
接入准备:激活前
调用接口前,请先完成以下步骤
步骤 1:提交企业资料
向技术支持提供以下信息:
| 资料项 | 说明 |
|---|---|
| 公司名称 | 注册法定公司名称(英文;如有中文名称可一并提供) |
| 公司地址 | 新加坡注册地址 |
| 联系人 | 技术接入负责人的姓名 |
| 联系电话 | 新加坡联系电话(+65) |
| 联系邮箱 | 用于接收技术通知的企业邮箱 |
| 开发技术栈 | 主要编程语言/框架,例如 Java、Python、.NET 等 |
步骤 2:获取开发参数
审核通过后,将获得:
| 参数 | 说明 |
|---|---|
vendor_sn | 服务商序列号 |
vendor_key | 服务商密钥 |
app_id | 应用 ID |
步骤 3:商户入网与激活码
完成商户入网,生成 store_sn,获取激活码(code),规划 device_id 命名,并实现签名算法(接口调用使用 MD5,回调验签使用 RSA SHA256WithRSA)。
完整接入步骤
从申请到首笔交易,分阶段完成入网与技术接入
vendor_sn vendor_key app_id app_key
merchant_sn store_sn
target_device_id → 用于订单推送(步骤 7)
code
terminal_sn terminal_key
target_device_id → 订单显示在 POS 终端out_trade_no → 等待支付;后续查询/通知获取 sn
/upay/v2/refund /upay/v2/query + 回调
完成商户与设备开通,取得调用方凭证;完成原始字节签名、首笔支付、查单、通知验签与退款联调;通过异常测试及上线清单后再切换生产。
端到端业务流程
订单推送场景下的完整支付生命周期
CREATED
→
PAID
→
REFUNDED
/
PARTIAL_REFUNDED
CANCELED
|
PAY_CANCELED
订单状态可继续变化:PAID 后可退款,PARTIAL_REFUNDED 后可继续退款;请同时判断交易流水类型和状态,详见响应与状态判定。
最佳实践
| 领域 | 建议 |
|---|---|
| 激活管理 | 安全持久化调用方 terminal_sn / terminal_key;激活与目标设备绑定分别管理。 |
| 密钥轮换 | 按接入配置调用 /terminal/checkin 并原子更新密钥;本页不承诺统一的每日签到频率。 |
| 订单号唯一性 | out_trade_no 在同一商户内唯一;同一业务保持原单号,结果未知时先查原单,禁止换号再次收款。 |
| 双重确认 | 回调与查询共同确认;同一订单的不同流水不能相互覆盖,旧通知不能回退已确认状态。 |
| 异常处理 | 发生网络超时后,先查询订单状态再重试,不要盲目重发。 |
| 对账 | 按商户、门店和业务日期核对支付、退款与账单;/mis/shift 不是资金结算到账确认。 |
| 日志 | 记录脱敏后的业务标识、请求时间、状态与错误码;不记录密钥、完整卡号或完整敏感报文。 |
| 幂等处理 | 按流水及状态处理回调去重;每个新退款业务生成退款号,同一退款结果不明时保留原号查询。 |
响应与状态判定
按下面四层依次判断。字段缺失、未知枚举或验签失败时,保留“待核实”,不要自动归为成功或失败。
| 层级 | 字段/示例 | 可以得出的结论 |
|---|---|---|
| HTTP | HTTP 2xx | 只说明收到 HTTP 响应;认证失败也可能返回 HTTP 200。 |
| 接口结果 | 顶层 result_code = "200" / "400" / "500" | 业务层可处理 / 请求错误 / 服务异常;400、500 或网络超时均不能单凭这一层推断资金结果。 |
| 业务结果 | biz_response.result_code | PUSH_SUCCESS / MIS_PUSH_SUCCESS=指令受理;查询 SUCCESS=查询执行成功;服务端退款看 REFUND_*。同时读取 error_code。 |
| 交易结果 | biz_response.data.type / status / order_status | 结合商户、client_sn/sn、total_amount 和流水类型确认。支付成功示例:PAYMENT + SUCCESS + PAID;退款后应分别记录原支付与退款结果。 |
订单与流水是两个对象
sn 是订单号,tsn 是交易流水号;一个订单可以先有 PAYMENT,再有多次 REFUND 或 CANCEL。未指定 refund_request_no 的查询可能返回最新退款流水。status=SUCCESS 必须与 type 一起解释。
| order_status | 处理方式 |
|---|---|
| CREATED | 尚未确认付款,继续等待并查单。 |
| PAID | 订单已支付;可以按幂等规则履约,但以后仍可能退款或撤销。 |
| PARTIAL_REFUNDED / REFUNDED | 分别表示部分/全额退款;核对指定退款流水,不能再次将订单记为新支付。 |
| PAY_CANCELED / CANCELED | 支付已关闭,或订单已取消/撤销。CANCELED 也可能来自未付款时的主动关单;这两个枚举都不能单独证明曾扣款或资金已退,须核对原支付/撤销流水、金额及渠道结果。 |
| PAY_ERROR / REFUND_INPROGRESS / REFUND_ERROR / CANCEL_INPROGRESS / CANCEL_ERROR | 按对应操作保留处理中或待核实,继续查询或升级处理;不能因为错误字样就再次扣款/退款。 |
流水 status 可包含 CREATED、IN_PROG、PRE_SUCCESS、ERROR_RECOVERY、ABORTING、SUCCESS、FAIL_CANCELED、ABORTED、FAIL_ERROR、REFUND_ERROR 等。不要仅实现 SUCCESS/FAIL 两个分支,也不要把新枚举默认视为终态。
关单受理但仍在执行
{
"result_code": "200",
"biz_response": {
"result_code": "MIS_PUSH_SUCCESS",
"error_code": "ORDER_CLOSE_ABORT_IN_PROGRESS"
}
}
上例需要继续查询原订单;它不能作为“已取消”的凭据。支付、退款和撤销的状态更新应分别记录,避免迟到消息回退订单。
请求规范与签名
新加坡接入域名由飞书接口文档确认。测试环境地址、凭证与真实扣款边界须在联调开通时单独获取,不能把此域名默认当作沙箱。
| 项目 | 规范 |
|---|---|
| 协议 | HTTPS |
| 请求方法 | POST |
| Content-Type | application/json |
| 编码 | UTF-8 |
平台接口仅支持 JSON 格式请求。请在 HTTP 请求头中设置 Content-Type: application/json。
所有请求体必须使用 UTF-8 编码,响应也使用相同编码。
调用所有平台接口均需要签名验证。
签名覆盖实际发送的 UTF-8 原始字节。先生成最终 JSON,再签名;字段顺序、空格、转义或末尾换行变化均需重新计算。
Authorization 使用调用方序列号与签名;交易接口中该序列号必须与 Body 的 terminal_sn 一致。
签名算法(V2):
待签名内容为 HTTP 请求体原始字节与密钥直接拼接:激活用 vendor_key,其余本页业务接口用 terminal_key。
其中 HASH 支持 MD5 和 SHA256:
- 默认使用
MD5 - 也可使用
SHA256,增强安全性 - 通过
Authorization-Type请求头指定算法(md5 或 sha256) - 省略
Authorization-Type时,默认使用 md5
签名请求头格式:
序列号与签名之间使用一个半角空格;算法值必须小写 md5 / sha256,十六进制签名比较不区分大小写。此处是 HASH(body + key),不是 HMAC。
所有响应参数均为 JSON 格式。
按字段类型解析:result_code 与金额等常用标量为字符串;biz_response / data / extended 为对象,集合为数组,错误字段可为空或省略。
SGD 金额用新加坡分的整数字符串,例如 SGD 1.00 = "100";不用浮点数。接口本身不通过示例金额自动选择币种,需确认商户/渠道币种配置。
| 适用范围 | 序列号 | 密钥 |
|---|---|---|
/terminal/activate | vendor_sn | vendor_key |
| 其他所有接口 | terminal_sn | terminal_key |
本地签名测试向量
下例仅验证字节拼接和编码,凭证是虚构值,不可直接调用支付 API;Body 末尾没有换行。完整示例的 selftest 使用同一 SHA256 向量。
body = {"terminal_sn":"TEST_TERMINAL","client_sn":"SG_TEST_001"}
secret_key = TEST_SECRET
md5 = e628a48f6c61626e8074bd049a960793
sha256 = 3425ab126f49ea26ec607af9d2d2c90225db75a43b8fabd01e28580d2080d00f
下面接口的 cURL 只示意报文形态,<sign> 必须按最终请求体实时计算;推荐先运行完整 Python 示例,避免签名与实际发送的 JSON 不一致。
回调验签
网关 V2 支付通知使用 SHA256withRSA;取消通知结构另见异步回调章节。请对原始请求体验签,验签通过前不处理业务。
Authorization 头作为 RSA 签名;它不带 terminal_sn 前缀。
2. 读取并保留原始 UTF-8 请求字节;不要先解析再序列化。
3. 使用对应环境的平台公钥;上线前确认公钥发放与轮换流程。
4. 使用平台公钥按 SHA256withRSA 验签;通过后再解析 JSON 并核对订单与金额。
5. 可靠保存合法通知后返回 HTTP 2xx + 纯文本 success;无效签名不更新订单。正常业务响应使用 V2 签名,验签对象是收到的原始响应字节。认证早期失败可能没有有效签名;这种响应只能用于排障,不能作为可信业务结果。
普通交易响应用本次请求的算法与成功匹配的 terminal_key;激活响应仍用 vendor_sn / vendor_key。签到成功响应改用返回的新 terminal_key,见签到章节。
终端激活
首次注册 ISV 调用方终端,获取接口凭证。目标支付设备的绑定是独立的准备步骤。
https://api.aimt-horizon.com/terminal/activate签名凭证: 使用 vendor_sn + vendor_key
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
app_id | String | 是 | 应用 ID |
code | String | 是 | 激活码(在商户平台生成) |
device_id | String(128) | 是 | 设备唯一 ID,例如 "MERCHANT_STORE_01" |
client_sn | String(50) | 否 | 第三方终端编号 |
name | String(128) | 否 | 终端显示名称 |
os_info | String(45) | 否 | 操作系统信息,例如 "Android 10" |
激活请求示例
服务端以 vendor_sn / vendor_key 签名;device_id 是调用方标识,不自动替代目标支付设备 TUSN。可选 sdk_version 为 SDK 版本字符串。成功响应还可能返回 merchant_sn、merchant_name、store_sn、store_name;保留归属信息以核对设备绑定。
{
"app_id": "EXAMPLE_APP_ID",
"code": "EXAMPLE_ACTIVATION_CODE",
"device_id": "ISVSTORE01REGISTER01",
"name": "Checkout 01"
}终端签到与密钥轮换
POST https://api.aimt-horizon.com/terminal/checkin。请求用当前终端凭证;签到频率按开通配置确认,勿在每次交易超时后自动签到。
| 字段 | 类型 | 要求 |
|---|---|---|
| terminal_sn | String | 必填;与请求头一致。 |
| return_store / return_time | String | 可选;字符串 "1" 分别请求门店信息/服务器毫秒时间。 |
| device_id / os_info / sdk_version | String | 可选;按调用方实际设备信息填写。 |
{"terminal_sn":"2101107140290972547","return_time":"1"}
成功响应的 biz_response.terminal_key 为新密钥。此接口是普通响应签名规则的例外:成功响应使用这个新密钥签名,而不是请求时的旧密钥。保持 HTTPS 证书校验,读取原始响应字节后解析出新密钥,用它验证该原始响应;校验通过后原子持久化新密钥,后续请求使用新值。失败响应仍按已匹配的请求密钥验证。
同一终端避免多个实例并发轮换,防止旧配置覆盖新密钥。服务端存在 next/current/last 过渡匹配,但不承诺旧密钥无限期可用。新密钥不得出现在日志、截图或前端配置中。
订单推送
将商户系统中的订单推送至专用支付终端(例如支持的P3、MT919设备等),支持扫码、银行卡支付
https://api.aimt-horizon.com/appPush/tradePush签名凭证: 使用 terminal_sn + terminal_key
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
terminal_sn | String(32) | 是 | 绑定来源系统的终端序列号 |
out_trade_no | String(32) | 是 | 同一商户内唯一,最多 32 字节,仅英文字母和数字;后续 client_sn 填同一值。 |
total_amount | String(10) | 是 | 正整数分,最多 10 位;例如 SGD 1.00 = "100"。渠道限额另行生效。 |
trade_time | String(13) | 是 | 发起推送时的 13 位 Unix 毫秒时间戳;每次调用生成当前值,不复制示例历史时间。 |
target_device_id | String(20) | 是 | 目标支付设备 ID,例如终端背面的 TUSN 编号 |
notify_url | String(128) | 是 | 支付结果通知地址,使用可公网访问的 HTTPS;通知重试见异步回调,不能用于推单重试。 |
cancel_notify_url | String(128) | 否 | 取消通知地址;具体触发路径依设备与路由而异,需联调验证;不能代替支付查单。 |
pay_type | String(32) | 否 | 常用值:1=银行卡、2=扫码、6=C 扫 B(顾客扫描商户收款码);多个值用半角逗号分隔,例如 1,2,6。其他枚举不代表新加坡已开通,见能力边界。 |
remark | String(16) | 否 | 订单备注,例如桌号、参考信息 |
out_trade_no 对应查询/服务端退款的 client_sn,同一商户内唯一;PUSH_SUCCESS 响应通常不返回 sn。
target_device_id 必须预先登记(扫描终端上的 TUSN 条码)。
PUSH_SUCCESS 后等待付款并查单;超时先查原订单,不能按通知的 1/5/30/600 秒间隔自动重推。
必须结合查询接口主动确认状态,不要仅依赖回调。
受理响应
{
"result_code": "200",
"biz_response": {
"result_code": "PUSH_SUCCESS"
}
}错误字段可能为 null 或省略。此响应通常没有 sn,也不承诺设备已显示订单或顾客已付款;保留原 out_trade_no,后续用它查单。常见拒绝与未知结果见错误码。
MIS 退款(设备端)
向支付终端推送退款指令,由终端设备执行退款操作并返回结果。
https://api.aimt-horizon.com/mis/refund签名凭证: 使用 terminal_sn + terminal_key
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
terminal_sn | String(32) | 是 | 绑定来源系统的终端序列号 |
out_trade_no | String(32) | 是 | 商户订单号(来自原始 tradePush 订单) |
target_device_id | String(20) | 是 | 目标支付设备 ID,例如终端背面的 TUSN 编号 |
refund_amount | String | 是 | 退款金额,以分为单位 |
refund_request_no | String(31) | 是 | 每个新退款业务的唯一请求号,按当前实现限制最多 31 个字符;结果未知时保留原号。 |
biz_source | String(128) | 是 | 业务来源 |
client_ip | String | 否 | 请求方 IP 地址 |
extended.refund_mode | String | 否 | 退款模式(cancel / refund),仅适用于 KPay POS |
每个新退款业务使用新的 refund_request_no;同一退款查询或排障使用原号。
out_trade_no 必须与原始 tradePush 订单一致。
MIS_PUSH_SUCCESS 只表示退款指令受理;通过查询原订单并携带 refund_request_no 确认该次退款。
结果未知时不要换号或切换到服务端退款再次提交;重复请求不承诺返回同一成功结果。
biz_source 在飞书参数表标为必填、当前 DTO 默认是 mis;为保持接入兼容,建议显式发送 "mis"。extended 是 JSON 对象,refund_mode 是其中的字段,不是名为 "extended.refund_mode" 的顶层字符串键。KPay 的 cancel/refund 模式必须按已开通设备约定使用。已核对的 KPay 网关规则:模式缺省或不为 refund 时须退清剩余可退金额;银行卡即使采用 refund 模式也不支持部分退款。
退款(服务端)
在商户、渠道和支付方式允许时从服务端发起退款。部分退款、多次退款、可退期限和手续费处理均受配置约束。
https://api.aimt-horizon.com/upay/v2/refund签名凭证: 使用 terminal_sn + terminal_key
时间限制: 按商户与海外渠道配置;不是统一的“支付完成后 3 个月”。
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
terminal_sn | String(32) | 是 | 原交易商户下的授权终端;跨门店退款还受权限与渠道规则限制。 |
refund_request_no | String(31) | 是 | 新退款业务的唯一请求号,1~31 个字符;同一退款结果未知时保留原号查询。 |
sn | String(16) | 条件必填 | 系统订单号(sn 与 client_sn 至少提供一个) |
client_sn | String(32) | 条件必填 | 商户订单号(sn 与 client_sn 至少提供一个) |
refund_amount | String(10) | 是 | 退款金额,以分为单位 |
operator | String(32) | 是 | 操作员名称,例如 "CASHIER-01" |
extended | Object | 否 | 扩展参数对象;渠道专属参数按已开通能力传入。 |
extended.refund_mode | String | 条件必填 | KPay 二维码部分退款时必填 refund;缺省或其他模式须退清剩余可退额。KPay 银行卡不支持部分退款。 |
| 参数 | 说明 |
|---|---|
biz_response.result_code | REFUND_SUCCESS=成功;REFUND_IN_PROGRESS=处理中;REFUND_FAIL=明确失败;REFUND_ERROR=异常待核实。 |
biz_response.data.order_status | REFUNDED(全额退款)/PARTIAL_REFUNDED(部分退款) |
biz_response.data.net_amount | 剩余金额(交易总金额减去累计退款金额) |
先查 net_amount 并在本地串行化同单退款;查询余额不是并发锁,不能据此保证另一个请求未占用可退额。
结果未知时带原 refund_request_no 查单;已成功退款号可能报重复,不把重放成功作为幂等契约。
手续费是否退还、退还金额与顾客到账时间以渠道、商户合同和实际配置为准。
KPay 二维码部分退款示例
下面对已支付的 SGD 1.00 KPay 二维码订单发起 SGD 0.10 的新退款;先确认剩余可退金额及该渠道、商户已开通部分退款。请求体不使用 out_trade_no,未获得 sn 时可改传同值的 client_sn。
extended 是 JSON 对象,refund_mode 是其内部字段。KPay 模式缺省或不为 refund 时须退清剩余可退额;KPay 银行卡即使采用 refund 也不支持部分退款。此约束同时适用于服务端和 MIS 退款;传入该模式只是必要条件,不代表渠道能力已开通。
{
"terminal_sn": "2101107140290972547",
"sn": "7892250221234567",
"refund_request_no": "SG20261022001R001",
"refund_amount": "10",
"operator": "CASHIER01",
"extended": {
"refund_mode": "refund"
}
}不要将该示例和 MIS 退款都发送给同一业务。对 REFUND_IN_PROGRESS / REFUND_ERROR 使用原退款号查单,只有核实该次流水成功才确认退款完成;顾客到账时间另由渠道决定。
订单查询
查询当前订单状态与支付结果,用于对账与异常处理。
https://api.aimt-horizon.com/upay/v2/query签名凭证: 使用 terminal_sn + terminal_key
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
terminal_sn | String(32) | 是 | 原交易商户下的有效终端;不能填 target_device_id。跨终端查询须保持同商户授权。 |
sn | String(16) | 条件必填 | 系统订单号(优先使用;sn 与 client_sn 至少提供一个) |
client_sn | String(32) | 条件必填 | 原 tradePush.out_trade_no;与 sn 至少传一个,同时传入时保持一致。 |
refund_request_no | String(31) | 否 | 查询指定退款时填写原退款请求号;省略时通常返回订单最新交易流水,可能是退款。 |
| 参数 | 说明 |
|---|---|
type | 流水类型:PAYMENT、REFUND、CANCEL 等;与 status 一起判断。 |
tsn | 平台交易流水号;同一订单可对应多条流水。 |
order_status | 订单聚合状态,见响应与状态判定;包括支付、退款、撤销的处理中及错误状态。 |
status | 当前交易流水状态,需结合 type 判断;SUCCESS 不一定是支付成功,也可能是退款成功。 |
total_amount | 原始交易金额 |
net_amount | 剩余金额(交易总金额减去退款金额) |
finish_time | 当前返回流水的完成时间,Unix 毫秒;退款查询时可能是退款完成时间,未完成时可缺省。 |
1. 推送后确认:推送订单后,查询并确认支付结果。
2. 支付状态未知:发生网络超时或异常时,查询实际状态。
3. 退款后确认:调用退款接口后,查询并确认退款结果。
4. 防止单边账:为操作员提供手动查询按钮。
按商户订单号查询
{
"terminal_sn": "2101107140290972547",
"client_sn": "SG20261022001"
}取得 sn 后优先用它替代 client_sn。通用查询支持原商户下的有效调用终端;目标设备归属错误、尚未创建支付单或权限问题都可能导致查不到,不能直接重新收款。
查询成功且付款成功的字段示例
{
"result_code": "200",
"biz_response": {
"result_code": "SUCCESS",
"data": {
"sn": "7892250221234567",
"client_sn": "SG20261022001",
"tsn": "7892250221234568",
"type": "PAYMENT",
"status": "SUCCESS",
"order_status": "PAID",
"total_amount": "100",
"net_amount": "100"
}
}
}查询成功也可返回处理中或失败的交易状态;请按四层规则判断。查询某次退款时额外传入原 refund_request_no,预期 type=REFUND,不要把它解释成 PAYMENT。
终端结算(交班)
向支付终端推送结算(交班)指令,完成日终结算操作。
https://api.aimt-horizon.com/mis/shift签名凭证: 使用 terminal_sn + terminal_key
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
terminal_sn | String(32) | 是 | 绑定来源系统的终端序列号 |
target_device_id | String(20) | 是 | 目标支付设备 ID,例如终端背面的 TUSN 编号 |
结算操作通常在营业日结束时执行。
发起结算前,请确保当日所有交易均已处理完成。
MIS_PUSH_SUCCESS 只表示交班指令受理。本组接口未确认通用交班结果查询或汇总回调;须按设备联调确认完成,不等同资金结算到账。
交班请求示例
{
"terminal_sn": "2101107140290972547",
"target_device_id": "TUSN12345678"
}在目标设备支持并开通时调用。接口未提供统一交班结果查询地址;请通过设备或已约定的渠道结果完成验收。
关单/撤销
关闭尚未完成支付的订单。当前通联/KPay 路径默认拒绝已明确为 PAID 的订单;已支付订单的资金退回应使用已开通的退款流程。关单与支付并发时仍须查单确认结果。
https://api.aimt-horizon.com/mis/close签名凭证: 使用 terminal_sn + terminal_key
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
terminal_sn | String(32) | 是 | 终端序列号 |
out_trade_no | String(32) | 是 | 商户订单号(来自原始 tradePush 订单) |
cancel_reason | String(20) | 是 | 撤销原因,最多 20 个字符 |
target_device_id | String(20) | 是 | 目标支付设备 ID |
cancel_notify_url | String(128) | 否 | 撤销结果通知的回调地址 |
biz_source | String | 否 | 业务来源,默认为 "mis" |
client_ip | String | 否 | 请求方 IP 地址 |
先查原订单;查单后仍可能完成付款,关单提示已支付时应重新查单。未支付订单也受预撤单条件、渠道和设备能力限制;MIS_PUSH_SUCCESS 仅表示受理,不能直接将本地订单标记为已撤销。
out_trade_no 必须与通过 tradePush 推送的原始订单一致。
ORDER_CLOSE_ABORT_IN_PROGRESS 表示关单仍在处理;PAY_TYPE_CANCEL_NOT_SUPPORTED 时按设备提示操作并查单,不盲目改走退款。
向顾客确认前,务必通过回调或查询接口核实撤销结果。
异步回调通知
支付平台通过 HTTP POST 向商户系统推送支付结果。必须实现回调处理,同时结合其他方式确认结果。
请求方法: POST Content-Type: application/json
验签方式: RSA SHA256WithRSA;从 Authorization 请求头获取 sign,使用公钥验证
| 参数 | 类型 | 说明 |
|---|---|---|
sn | String(16) | 系统订单号 |
client_sn | String(32) | 商户订单号(out_trade_no) |
trade_no | String(64) | 支付渠道订单号(支付成功时提供) |
type | String | 流水类型:PAYMENT、REFUND、CANCEL 等;与 status 一起判断。 |
tsn | String | 平台交易流水号;同一订单可对应多条流水。 |
client_tsn | String | 该交易流水的外部标识;退款时用于关联原退款业务。 |
status | String(32) | 交易流水状态 |
order_status | String(32) | 当前订单状态 |
total_amount | String(10) | 交易总金额 |
net_amount | String(10) | 订单剩余未退原始金额;不是扣手续费后的结算净收入。 |
payway | String | 渠道支付方式编码,例如 PayNow=3001;与推单 pay_type 枚举不同。 |
finish_time | String(13) | 当前流水完成时间(Unix 毫秒);退款通知可能是退款完成时间。 |
subject | String(64) | 交易摘要 |
HTTP 状态须为 2xx,Body 必须恰好是小写 success,不含引号、空格或换行;验签并可靠保存后再应答。
按流水类型、tsn 与状态实现业务幂等,并核对商户/订单范围;不能只按 sn 永久去重,否则会漏处理后续退款。
执行业务逻辑前必须验证签名。
回调与主动轮询查询应配合使用,不要仅依赖回调。 遇到冲突时按同一订单及流水重新查询核实;旧通知不得覆盖更新状态,持续不一致进入人工核对。
通知投递与接收实现
支付通知示例
以下为虚构值的最小字段示例;真实通知为直接 JSON 对象,不包裹 biz_response。tsn/type/status 标识当前流水和状态,client_tsn 是该流水的外部标识,退款流水不能当成新的付款。
{
"sn": "7892250221234567",
"client_sn": "SG20261022001",
"tsn": "7892250221234568",
"client_tsn": "SG20261022001",
"type": "PAYMENT",
"status": "SUCCESS",
"order_status": "PAID",
"total_amount": "100",
"net_amount": "100",
"payway": "3001",
"finish_time": "1792627201000"
}
Node.js 验签函数
使用 Node.js 标准库;rawBody 必须是尚未经过 JSON 中间件改写的原始 Buffer。此函数按本地 SDK 的 Base64 编码实现;上线前用目标环境的含中文通知样本验签通过,详见核验范围。
const { verify } = require("node:crypto");
function verifyNotification(rawBody, authorization, publicKeyPem) {
if (!Buffer.isBuffer(rawBody) || !authorization) return false;
try {
return verify(
"RSA-SHA256",
rawBody,
publicKeyPem,
Buffer.from(authorization, "base64")
);
} catch {
return false;
}
}
// Read raw bytes before any JSON middleware.
// Parse JSON only after verification succeeds.
// Persist the valid event before responding with:
// HTTP 200, Content-Type: text/plain, body exactly: success
投递规则与应答
本地网关实现首次立即投递;失败后依次等待 1、5、30、600 秒,最多重试四次(含首次最多五次)。非 2xx、网络失败、空 Body、带引号或换行的 success 都会导致重试。不要依赖永久重试;持续漏通知由查单和对账补偿。先验签并可靠保存,再快速应答,耗时业务异步处理;没有确认统一的接收超时 SLA。
HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 7 success
取消通知是不同的载荷
已核对的预撤单路径(订单尚未生成且允许预撤单)可能向 cancel_notify_url 发送以下结构;它没有支付通知的 sn/type/order_status,不能据此认定顾客已退款。取消通知覆盖范围依设备/路由而异,必须联调;/mis/close 可显式传入取消通知地址。
在已核对的通联/KPay 预撤单路径中,代理将请求中的 terminal_sn 转为目标支付终端号,网关将此值写入取消通知。同商户双终端示例:调用方为 2101107140290972547,目标支付终端为 2101107140290972548;下例返回后者。验签后按 out_trade_no 及已核实的商户、设备映射关联,不能强制要求通知终端号等于请求方终端号。
{
"terminal_sn": "2101107140290972548",
"out_trade_no": "SG20261022001",
"cancel_reason": "Customer cancelled",
"cancel_time": "1792627201000"
}
使用相同的网关 RSA 验签和纯文本应答规则。按原订单及取消业务去重,并查询核实最终结果;不要要求取消通知一定具有支付流水字段。
签名汇总
所有接口调用均采用 V2 签名机制。签名计算方式为 HEX(HASH(request_body_bytes + secret_key)),其中 HASH 支持 MD5 和 SHA256。通过 Authorization-Type 请求头指定算法,默认为 md5。
| 接口类型 | 凭证 | 算法(V2) |
|---|---|---|
| /terminal/activate | vendor_sn + vendor_key | MD5 或 SHA256(十六进制) |
| /terminal/checkin | terminal_sn + terminal_key | 请求用当前密钥;成功响应用返回的新密钥,见签到章节。 |
| /appPush/tradePush | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) |
| /mis/refund | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) |
| /upay/v2/refund | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) |
| /upay/v2/query | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) |
| /mis/shift | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) |
| /mis/close | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) |
| 异步回调通知 | 平台公钥 | RSA SHA256WithRSA |
超时、重复与结果恢复
客户端等待结束只说明未获得可信结果。商户系统应保留独立的“结果待确认”状态,保存原业务标识,暂停再次收款或退款。
| 触发条件 | 立即处理 | 恢复/停止条件 |
|---|---|---|
| 推单超时、断连、5xx、无效响应签名 | 保留原 out_trade_no 与请求参数;用 client_sn 查原单,已有 sn 则优先用 sn。不要换单号、换设备或改走另一个支付通道再次扣款。 | 查询/可信通知确认已支付则幂等完成;仍未知则继续核实。 |
| 推单受理后暂时查不到订单 | 设备可能尚未创建支付交易;核对调用终端与目标设备所属商户,等待付款流程继续。 | 查不到不是未受理的证明;确认设备及平台原操作不会继续执行后,才按约定重新发起。 |
| 查询显示处理中或错误恢复 | 保持原订单;采用有上限的退避查询并等待通知。 | 建议客户端 2、5、10 秒逐步退避,随后低频补查;这是接入建议,不是平台频控或时效承诺。门店等待超时后进入待核对,不改成付款失败。 |
| 退款超时 / REFUND_IN_PROGRESS / REFUND_ERROR | 用原 sn/client_sn + refund_request_no 查询;不换退款号,不切换设备/服务端退款路径重复提交。 | 确认该次退款 SUCCESS 后记账;明确失败后按业务规则决定后续操作,长期不明转人工。 |
| 关单与支付并发 | 保留关单请求与原支付结果;ORDER_CLOSE_ABORT_IN_PROGRESS 继续查单。 | 以核实后的订单及流水结果更新;如已收款且未撤销,按允许的退款流程处理,不能直接关闭本地订单。 |
| 重复或乱序通知 | 验签、持久化;以商户/订单 + type + tsn + status 等构造处理记录,并用本地原子状态更新防止重复履约。 | 去重已执行的业务效果;同一 sn 的新退款不能丢弃,迟到 PAYMENT 通知不能覆盖最新退款状态。 |
| 限流、平台/渠道临时故障 | 降低并发并退避;支付/退款请求先查询原业务,读取接口层和业务层错误码。 | 恢复后继续原业务核实;不无限循环、不将批量重发作为恢复策略。 |
幂等边界
本组接口没有确认统一的 Idempotency-Key 请求头、固定幂等保留窗口或“重复请求返回原响应”的承诺。out_trade_no/client_sn 的商户内唯一性、refund_request_no 的业务身份,以及商户自己实现的原子记账是不同约束。新业务用新标识;同一业务结果不明时不能换标识。
时间与对账
请求/响应的毫秒时间戳是 Unix 时间;门店展示建议显式使用 Asia/Singapore(UTC+08:00)。交易日、账务日、日切点、账单格式、退款入账日和结算到账周期须按开通资料确认。保存平台订单、商户订单、支付/退款流水和业务日期的关联;net_amount 不等于扣费后到账额,/mis/shift 不提供银行到账证据。
错误码与排障
先检查顶层 result_code/error_code,再检查 biz_response.result_code/error_code/error_code_standard。下表为已核对的常见默认码;部署映射可能改变错误文案或标准码,程序不得按中文/英文提示文本分支。
| 错误/症状 | 含义与下一步 |
|---|---|
| ILLEGAL_SIGN | 对比 Header 与 Body 的 terminal_sn;确认激活/交易凭证未混用、算法小写、使用最终原始 Body、密钥未过期。先跑签名测试向量;不向支持人员提供密钥。 |
| INVALID_PARAM | 检查字段类型、长度、正整数金额和必填条件;修正参数前先判断原业务是否可能已受理。 |
| PRE_AUTH_PAY_TYPE_MIX_ERROR | 预授权类型与其他支付类型组合不允许;按已开通的设备能力重新选择类型。 |
| PUSH_DEVICE_SN_ERROR / TERMINAL_SN_UN_BIND | 设备号不存在或来源终端已解绑;核对 TUSN、激活凭证及绑定关系后再测试。 |
| STORE_NOT_MARCH / MERCHANT_NOT_MARCH | 来源终端与目标设备的门店/商户关系不满足要求;注意 MARCH 是接口原始拼写。修复绑定,不绕过商户授权。 |
| DEVICE_TYPE_NOT_SUPPORT | 该路由/机型不支持指令,确认设备、固件与应用开通。 |
| DEVICE_OFFLINE / DEVICE_STATUS_UN_KNOW | 相关路由检测到设备离线/状态未知;恢复网络与设备登录,查询原单后再处理。不是每种路由都会返回这些码。 |
| PUSH_FAIL / MIS_PUSH_FAIL / ERROR / UNKNOWN_SYSTEM_ERROR | 按未知结果恢复:保留业务标识,查原单并收集错误信息,不能只见 FAIL 就重新扣款。 |
| ORDER_CLOSE_ABORT_IN_PROGRESS | 关单处理中,即使 MIS_PUSH_SUCCESS 也需继续查询。 |
| ORDER_CLOSE_ERROR / UPAY_QUERY_ORDER_ERROR | 关单失败或查单异常,先查询原支付状态;持续不明进入人工核对。 |
| PAY_TYPE_CANCEL_NOT_SUPPORTED | 该支付方式不支持当前取消动作;按设备/渠道规则处理并查单,不能据此判定已退款。 |
| REFUND_IN_PROGRESS / REFUND_ERROR | 这是退款业务结果码;用原退款号查单,不换号重退。 |
| ILLEGAL_REQUEST 或 HTTP 429/限流提示 | 可能触发入口限流;降低查询频率/并发。具体配额按分配配置,支付副作用仍需按原业务核实。 |
转人工时提供的诊断信息
环境、商户/门店标识、调用方 terminal_sn、目标设备号、out_trade_no/client_sn、sn、tsn、退款号、请求发生时间及时区、接口路径、HTTP 状态、两层结果码、平台返回的追踪标识(如有)、已尝试的查询及设备现象。请求/响应只提供脱敏样本;移除密钥、完整卡号、个人敏感信息。通过开户时指定的技术支持渠道提交,持续保留待核对状态。
联调验收与上线
下列用例应在授权测试环境执行并留存脱敏证据。本次文档校验不等于这些用例已在真实终端/渠道通过;没有模拟器的场景需安排受控联调。
| 场景与触发方式 | 必须验证的行为 | 通过证据 |
|---|---|---|
| 成功支付:推送新单并在设备完成付款 | 受理后等待,按查询/验签通知确认;只履约一次。 | 同一 out_trade_no/sn、金额与 PAYMENT 流水一致。 |
| 超时:测试代理在受理后丢弃响应 | 不换订单号重扣,按 client_sn 找回原单。 | 原单恢复且无重复收款。 |
| 未付款/设备离线:断开测试设备网络 | 不把推送失败或暂时无订单当作资金结果;恢复后查原单。 | 设备、推送和查单记录可解释。 |
| 并发/重复提交:同一业务重复调用 | 商户本地限制重复提交,保留原标识并核实结果。 | 只有一笔预期资金动作;不依赖服务端重放响应。 |
| 验签:篡改 Body 字节、签名或错误公钥 | 拒绝无效回调,不产生履约;合法样本可验签。 | 包含中文、空白、转义的原始样本也通过正确验签。 |
| 回调重试:返回 HTTP 500 或带引号的 success | 通知重试;改回纯文本 success 后停止。 | HTTP 状态与精确响应字节、投递时间记录。 |
| 重复/乱序:在本地测试桩重放合法通知快照 | 同一业务效果一次;支付旧消息不覆盖新退款。 | 幂等记录与最终查单一致。 |
| 部分/多次退款:仅测试已开通能力 | 记录每次退款号,查询指定退款;未知结果不换号。 | 累计退款、net_amount 和原订单匹配,无超退。 |
| 退款结果丢失:丢弃退款响应 | 按原退款号恢复;不改走另一退款路径重复提交。 | 指定退款流水明确,资金动作唯一。 |
| 支付与关单竞争:支付时发起关闭 | 对 ORDER_CLOSE_ABORT_IN_PROGRESS 持续核实;不提前声明取消。 | 最终支付/撤销结果与本地记录一致。 |
| 签到:新旧密钥切换及多实例配置更新 | 成功响应用新密钥校验;后续请求可用,配置不回退。 | 脱敏校验结果、版本记录,无密钥泄漏。 |
| 跨日对账与交班:按已确认日切规则执行 | 区分交易完成、交班执行与资金到账,核对支付/退款。 | 账单与业务标识对应,时区明确。 |
上线前确认
- 生产商户、门店、目标设备与调用方凭证绑定一致,币种和支付方式开通完成。
- 测试/生产 URL、公钥、密钥、回调域名分离;密钥安全存储,TLS 证书有效。
- 支付、退款、通知、超时和重复业务用例有可回溯证据,未知状态有人工接管流程。
- 已确认频控、设备固件、退款期限/权限/手续费、取消回调范围、对账与结算规则。
- 配置监控和支持联系人;先按约定完成小额生产验证,再逐步放量。
维护依据与待确认项
本页依据现有接入文档、MIS 专用收款设备接口文档(读取修订号 407)及以下本地代码核对。组织方式参考《Stripe 文档设计调研与聚合支付平台指导建议》:先完成业务任务,再深入接口参考,给出异常恢复与验收证据。Stripe 的接口或幂等规则没有被移植为 AiMT 契约。
代码核对范围与差异记录
| 来源与版本 | 核对内容 |
|---|---|
upay-api(仓库 api)9b55d08268a7 | internal/router/router.go:129,146;internal/auth/auth.go:113,218,343;internal/router/admin/admin.go:154。公网路由、原始字节签名、Header/Body 一致性、签到新密钥。 |
app-push-servicef2f1555d095c | MisTradePushController.java:45,161、MisPushApiExceptionEnumV2.java、MisServiceImpl.java:177、AllinpayServices.java:35,114。推送结果码、设备归属及通知转发范围。 |
upay-frontend-proxye1238c7 | MisPushController.java:23;MisPushServiceImpl.java:109,166,273。退款参数、目标支付终端转换、client_sn 映射。 |
upay-gatewayf5f8dbc7e0ed | UpayServiceImpl.java:531,1397,1410,1529;DataRepository.java:142;RefundProcessor.java:484,787,916;ClientNotifier.java:85,276,300;TransactionResponder.java:93,133。查询作用域、退款状态、回调与重试。 |
| RSA 编码补充源码 | 本地 mpay-sdk-homebrew/RsaSignature.java:68,199(4c5037791fee)采用 Base64。该本地 SDK 版本与 gateway 声明的 2.7.6 不同,须以目标环境真实签名样本完成最终验签联调。 |
差异处理:飞书表格中的 PUSH_SUCCESSS 按实现纠正为 PUSH_SUCCESS;退款示例的 refund_client_tsn 按参数表和实现纠正为 refund_request_no;退款号按已核对的 31 字符限制;通知 1/5/30/600 秒仅用于平台回调重试。
/mis/query 在入口已注册,但当前 frontend-proxy 没有对应实现,故本页使用已核对的 /upay/v2/query。tradePush 的 cancel_notify_url 在部分通联/KPay 转发路径未传递,不承诺所有设备均可收到取消通知。代码核对不是目标环境部署验证。
联调/上线前待确认
| 待确认项 | 确认方 / 所需证据 |
|---|---|
| 测试环境与凭证、真实扣款边界、商户 SGD 配置 | 平台接入团队:环境清单与可重复的测试样例。 |
| 机型/固件、pay_type 映射、退款与撤销能力 | 设备与渠道负责人:目标设备的成功/失败/处理中用例。 |
| 激活码有效期、重新激活、签到频率和公钥轮换 | 终端与平台负责人:当前开户说明及目标环境验签样本。 |
| 退款期限、跨店权限、手续费、资金结算及对账 | 渠道/商户运营:当前合同、配置和账单样例。 |
| 频控、业务确认时限、取消通知覆盖、交班完成确认 | 平台与设备负责人:配置或实测证据;不从本地默认实现推定线上 SLA。 |
本次修订
2026-10-22:补充首笔交易、四层结果判定、异常恢复、错误码与测试清单;修正重试订单号、退款号语义、回调原文验签/应答/去重、签到响应密钥、退款和交班能力边界。保留既有章节锚点与中英切换。本次仅修改文档,不改变任何 API 行为。