文档目录

AiMT 新加坡

面向新加坡金融机构、独立软件开发商(ISV)及支付服务商的推送支付接入方案。将订单推送至专用支付终端,通过 AiMT 完成支付、退款、查询、结算与撤销等业务操作。

🔗 POST /appPush/tradePush
🌐 HTTPS / JSON / UTF-8
🔐 MD5 / SHA256 签名

适用范围与能力

适用于新加坡门店收银系统通过 AiMT 将订单推送到已开通的专用支付设备。服务端负责签名、保存订单和确认结果;收银设备负责展示与执行付款。本页覆盖调用链,不代表所有渠道、机型及固件都已开通全部能力。

文档核对日期:2026-10-22 · 地区:新加坡 · 接入协议:V2 签名 · 依据与待确认项

任务接口完成判据与边界
注册调用方/terminal/activate获得并安全保存 terminal_sn / terminal_key;目标设备另外绑定。
更新密钥/terminal/checkin新密钥校验并原子持久化;不替代设备注册。
收款/appPush/tradePushPUSH_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 请求。

  1. 备齐配置。从安全配置或环境变量读取 AIMT_BASE_URL、AIMT_TERMINAL_SN、AIMT_TERMINAL_KEY、AIMT_TARGET_DEVICE_ID、AIMT_NOTIFY_URL。设置同一商户内唯一的 AIMT_ORDER_ID(1~32 位英文/数字)。回调接收端应先按通知规范部署。
  2. 确认测试范围。核实测试商户、SGD、设备及 pay_type=1,2,6 已开通后设置 AIMT_TEST_CONFIRMED=1。例子下单金额为 "100",即 SGD 1.00;这个开关只是本地防误操作,不能把生产环境变成沙箱。
  3. 先运行签名自检,再推送一次。Python 3 标准库示例无第三方依赖。自检无需网络。推送预期为 result_code="200" 且 biz_response.result_code="PUSH_SUCCESS",此时不履约。
  4. 在指定设备付款。核对设备上的金额与商户订单;保留设备流水,等待服务端通知,并使用相同 AIMT_ORDER_ID 执行 query。
  5. 确认结果。核对 client_sn、金额及 PAYMENT / SUCCESS / PAID,持久化 sn、tsn。后续可设置 AIMT_ORDER_SN 优先按平台订单号查询。不明结果按恢复流程处理。
  6. 验证退款。按已开通的退款路径发起一个新退款业务,记录退款号;设置 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 不算通过。

方案概览

五项核心能力,覆盖支付业务全流程

1
终端激活
一次性终端注册
2
订单推送
向支付终端推送订单
3
退款
退款能力及限制按渠道开通
4
查询
实时查询订单状态
5
回调
异步通知交易结果

关键术语

术语说明
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)。

完整接入步骤

从申请到首笔交易,分阶段完成入网与技术接入

阶段 1 · 接入准备
📋
步骤 1
提交申请
向平台支持团队提交企业资料、联系人和技术栈信息
ISV → AiMT
产出: 审核通过 ✅
🔑
步骤 2
获取开发参数
AiMT 根据审核通过的申请发放服务商凭证
AiMT → ISV
产出: vendor_sn vendor_key app_id app_key
🏪
步骤 3
商户入网
ISV 提交商户资料 → AiMT 协助登记门店并生成 store_sn
ISV → AiMT
产出: merchant_sn store_sn
阶段 2 · 终端绑定
📱
步骤 4
绑定 POS 终端
将 target_device_id 绑定到门店
AiMT
产出: target_device_id → 用于订单推送(步骤 7)
🎫
步骤 5
生成激活码
AiMT 协助生成激活码,将门店与设备绑定
AiMT
产出: code
阶段 3 · 接口接入
🔐
步骤 6
激活终端
调用 /terminal/activate,将 ISV 设备注册为平台接口调用方
接口调用
产出: terminal_sn terminal_key
⚠️ 将 ISV/服务商设备注册为平台 API 调用方
💳
步骤 7
推送订单
调用 /appPush/tradePush,使用步骤 4 的 target_device_id → 订单显示在 POS 终端
接口调用
产出: out_trade_no → 等待支付;后续查询/通知获取 sn
🔄
步骤 8
其他接口操作
退款、查询、回调验签,持续管理交易生命周期
接口调用
产出: /upay/v2/refund /upay/v2/query + 回调
📋
快速检查清单(供参考):
完成商户与设备开通,取得调用方凭证;完成原始字节签名、首笔支付、查单、通知验签与退款联调;通过异常测试及上线清单后再切换生产。

端到端业务流程

订单推送场景下的完整支付生命周期

1 激活(首次接入):通过 /terminal/activate 注册调用方系统,保存 terminal_sn + terminal_key;另行确认目标设备绑定。
2 订单推送:调用 /appPush/tradePush,PUSH_SUCCESS 只表示推送受理;支付单 sn 需从后续查询或通知获得。
3 顾客付款:顾客扫码或刷卡 → 终端处理支付
4 接收结果:结果回调至 notify_url,可通过 /upay/v2/query 主动查询
5 退款(按需):调用 /upay/v2/refund → 查询确认 → 更新商户系统
📊订单状态流转
CREATED → PAID → REFUNDED / PARTIAL_REFUNDED
CANCELED | PAY_CANCELED

订单状态可继续变化:PAID 后可退款,PARTIAL_REFUNDED 后可继续退款;请同时判断交易流水类型和状态,详见响应与状态判定。

最佳实践

领域建议
激活管理安全持久化调用方 terminal_sn / terminal_key;激活与目标设备绑定分别管理。
密钥轮换按接入配置调用 /terminal/checkin 并原子更新密钥;本页不承诺统一的每日签到频率。
订单号唯一性out_trade_no 在同一商户内唯一;同一业务保持原单号,结果未知时先查原单,禁止换号再次收款。
双重确认回调与查询共同确认;同一订单的不同流水不能相互覆盖,旧通知不能回退已确认状态。
异常处理发生网络超时后,先查询订单状态再重试,不要盲目重发。
对账按商户、门店和业务日期核对支付、退款与账单;/mis/shift 不是资金结算到账确认。
日志记录脱敏后的业务标识、请求时间、状态与错误码;不记录密钥、完整卡号或完整敏感报文。
幂等处理按流水及状态处理回调去重;每个新退款业务生成退款号,同一退款结果不明时保留原号查询。

响应与状态判定

按下面四层依次判断。字段缺失、未知枚举或验签失败时,保留“待核实”,不要自动归为成功或失败。

层级字段/示例可以得出的结论
HTTPHTTP 2xx只说明收到 HTTP 响应;认证失败也可能返回 HTTP 200。
接口结果顶层 result_code = "200" / "400" / "500"业务层可处理 / 请求错误 / 服务异常;400、500 或网络超时均不能单凭这一层推断资金结果。
业务结果biz_response.result_codePUSH_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://api.aimt-horizon.com

新加坡接入域名由飞书接口文档确认。测试环境地址、凭证与真实扣款边界须在联调开通时单独获取,不能把此域名默认当作沙箱。

📋请求规范
项目规范
协议HTTPS
请求方法POST
Content-Typeapplication/json
编码UTF-8
🔐签名方法

平台接口仅支持 JSON 格式请求。请在 HTTP 请求头中设置 Content-Type: application/json。

所有请求体必须使用 UTF-8 编码,响应也使用相同编码。

调用所有平台接口均需要签名验证。

签名覆盖实际发送的 UTF-8 原始字节。先生成最终 JSON,再签名;字段顺序、空格、转义或末尾换行变化均需重新计算。

Authorization 使用调用方序列号与签名;交易接口中该序列号必须与 Body 的 terminal_sn 一致。

签名算法(V2):

待签名内容为 HTTP 请求体原始字节与密钥直接拼接:激活用 vendor_key,其余本页业务接口用 terminal_key。

sign = HEX(HASH(request_body_bytes + secret_key))

其中 HASH 支持 MD5 和 SHA256:

  • 默认使用 MD5
  • 也可使用 SHA256,增强安全性
  • 通过 Authorization-Type 请求头指定算法(md5 或 sha256)
  • 省略 Authorization-Type 时,默认使用 md5

签名请求头格式:

Authorization: <terminal_sn> <sign> Authorization-Type: md5 (or sha256)

序列号与签名之间使用一个半角空格;算法值必须小写 md5 / sha256,十六进制签名比较不区分大小写。此处是 HASH(body + key),不是 HMAC。

所有响应参数均为 JSON 格式。

按字段类型解析:result_code 与金额等常用标量为字符串;biz_response / data / extended 为对象,集合为数组,错误字段可为空或省略。

SGD 金额用新加坡分的整数字符串,例如 SGD 1.00 = "100";不用浮点数。接口本身不通过示例金额自动选择币种,需确认商户/渠道币种配置。

🔑凭证使用范围
适用范围序列号密钥
/terminal/activatevendor_snvendor_key
其他所有接口terminal_snterminal_key
📤请求示例
curl --request POST \ --url https://api.aimt-horizon.com/appPush/tradePush \ --header 'Authorization: 2101107140290972547 <sign>' \ --header 'Authorization-Type: md5' \ --header 'Content-Type: application/json' \ --data '{ "terminal_sn": "2101107140290972547", "out_trade_no": "SG20261022001", "total_amount": "100", "trade_time": "1792627200000", "target_device_id": "TUSN12345678", "notify_url": "https://your-system.com/api/payment/callback" }'

本地签名测试向量

下例仅验证字节拼接和编码,凭证是虚构值,不可直接调用支付 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;取消通知结构另见异步回调章节。请对原始请求体验签,验签通过前不处理业务。

1. 取整个 Authorization 头作为 RSA 签名;它不带 terminal_sn 前缀。 2. 读取并保留原始 UTF-8 请求字节;不要先解析再序列化。 3. 使用对应环境的平台公钥;上线前确认公钥发放与轮换流程。 4. 使用平台公钥按 SHA256withRSA 验签;通过后再解析 JSON 并核对订单与金额。 5. 可靠保存合法通知后返回 HTTP 2xx + 纯文本 success;无效签名不更新订单。
📨响应签名验证

正常业务响应使用 V2 签名,验签对象是收到的原始响应字节。认证早期失败可能没有有效签名;这种响应只能用于排障,不能作为可信业务结果。

响应头: Authorization: <terminal_sn> <response_sign>

普通交易响应用本次请求的算法与成功匹配的 terminal_key;激活响应仍用 vendor_sn / vendor_key。签到成功响应改用返回的新 terminal_key,见签到章节。

终端激活

首次注册 ISV 调用方终端,获取接口凭证。目标支付设备的绑定是独立的准备步骤。

🔗接口信息
接口地址: POST https://api.aimt-horizon.com/terminal/activate
签名凭证: 使用 vendor_sn + vendor_key
📥请求参数
参数类型是否必填说明
app_idString是应用 ID
codeString是激活码(在商户平台生成)
device_idString(128)是设备唯一 ID,例如 "MERCHANT_STORE_01"
client_snString(50)否第三方终端编号
nameString(128)否终端显示名称
os_infoString(45)否操作系统信息,例如 "Android 10"
📤响应
{ "result_code": "200", "biz_response": { "terminal_sn": "10298371039", "terminal_key": "EXAMPLE_TERMINAL_KEY" } }
⚠️
注意: 将 terminal_sn / terminal_key 加密持久化;不要用重复激活恢复支付超时。激活码有效期、设备重复激活与解绑规则需在开户时确认。示例凭证均为虚构值。

激活请求示例

服务端以 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_snString必填;与请求头一致。
return_store / return_timeString可选;字符串 "1" 分别请求门店信息/服务器毫秒时间。
device_id / os_info / sdk_versionString可选;按调用方实际设备信息填写。
{"terminal_sn":"2101107140290972547","return_time":"1"}

成功响应的 biz_response.terminal_key 为新密钥。此接口是普通响应签名规则的例外:成功响应使用这个新密钥签名,而不是请求时的旧密钥。保持 HTTPS 证书校验,读取原始响应字节后解析出新密钥,用它验证该原始响应;校验通过后原子持久化新密钥,后续请求使用新值。失败响应仍按已匹配的请求密钥验证。

同一终端避免多个实例并发轮换,防止旧配置覆盖新密钥。服务端存在 next/current/last 过渡匹配,但不承诺旧密钥无限期可用。新密钥不得出现在日志、截图或前端配置中。

订单推送

将商户系统中的订单推送至专用支付终端(例如支持的P3、MT919设备等),支持扫码、银行卡支付

🔗接口信息
接口地址: POST https://api.aimt-horizon.com/appPush/tradePush
签名凭证: 使用 terminal_sn + terminal_key
📥请求参数
参数类型是否必填说明
terminal_snString(32)是绑定来源系统的终端序列号
out_trade_noString(32)是同一商户内唯一,最多 32 字节,仅英文字母和数字;后续 client_sn 填同一值。
total_amountString(10)是正整数分,最多 10 位;例如 SGD 1.00 = "100"。渠道限额另行生效。
trade_timeString(13)是发起推送时的 13 位 Unix 毫秒时间戳;每次调用生成当前值,不复制示例历史时间。
target_device_idString(20)是目标支付设备 ID,例如终端背面的 TUSN 编号
notify_urlString(128)是支付结果通知地址,使用可公网访问的 HTTPS;通知重试见异步回调,不能用于推单重试。
cancel_notify_urlString(128)否取消通知地址;具体触发路径依设备与路由而异,需联调验证;不能代替支付查单。
pay_typeString(32)否常用值:1=银行卡、2=扫码、6=C 扫 B(顾客扫描商户收款码);多个值用半角逗号分隔,例如 1,2,6。其他枚举不代表新加坡已开通,见能力边界。
remarkString(16)否订单备注,例如桌号、参考信息
📤调用示例
curl --request POST 'https://api.aimt-horizon.com/appPush/tradePush' \ --header 'Authorization: 2101107140290972547 <sign>' \ --header 'Authorization-Type: sha256' \ --header 'Content-Type: application/json' \ --data '{ "terminal_sn": "2101107140290972547", "out_trade_no": "SG20261022001", "total_amount": "100", "trade_time": "1792627200000", "target_device_id": "TUSN12345678", "notify_url": "https://your-system.com/api/payment/callback", "pay_type": "1,2,6", "remark": "Table 12" }'
📋业务流程
收银员在商户系统创建订单 → 调用 tradePush,将订单推送至支付终端 → 终端显示订单并提示付款 → 顾客付款(扫码/银行卡) → 结果回调至 notify_url → 商户系统更新订单状态
💡
关键规则:
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 退款(设备端)

向支付终端推送退款指令,由终端设备执行退款操作并返回结果。

🔗接口信息
接口地址: POST https://api.aimt-horizon.com/mis/refund
签名凭证: 使用 terminal_sn + terminal_key
📥请求参数
参数类型是否必填说明
terminal_snString(32)是绑定来源系统的终端序列号
out_trade_noString(32)是商户订单号(来自原始 tradePush 订单)
target_device_idString(20)是目标支付设备 ID,例如终端背面的 TUSN 编号
refund_amountString是退款金额,以分为单位
refund_request_noString(31)是每个新退款业务的唯一请求号,按当前实现限制最多 31 个字符;结果未知时保留原号。
biz_sourceString(128)是业务来源
client_ipString否请求方 IP 地址
extended.refund_modeString否退款模式(cancel / refund),仅适用于 KPay POS
📤请求示例
{ "terminal_sn": "2101107140290972547", "out_trade_no": "SG20261022001", "target_device_id": "TUSN12345678", "refund_amount": "10", "refund_request_no": "SG20261022001_R001", "biz_source": "mis" }
📤响应示例(指令受理)
{ "result_code": "200", "error_message": null, "error_code": null, "biz_response": { "result_code": "MIS_PUSH_SUCCESS", "error_code": null, "error_message": null } }
📤响应示例(失败)
{ "result_code": "200", "error_message": null, "error_code": null, "biz_response": { "result_code": "MIS_PUSH_FAIL", "error_code": "TERMINAL_SN_UN_BIND", "error_message": "Terminal SN is unbound, push failed" } }
⚠️
注意:
每个新退款业务使用新的 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 模式也不支持部分退款。

退款(服务端)

在商户、渠道和支付方式允许时从服务端发起退款。部分退款、多次退款、可退期限和手续费处理均受配置约束。

🔗接口信息
接口地址: POST https://api.aimt-horizon.com/upay/v2/refund
签名凭证: 使用 terminal_sn + terminal_key
时间限制: 按商户与海外渠道配置;不是统一的“支付完成后 3 个月”。
📥请求参数
参数类型是否必填说明
terminal_snString(32)是原交易商户下的授权终端;跨门店退款还受权限与渠道规则限制。
refund_request_noString(31)是新退款业务的唯一请求号,1~31 个字符;同一退款结果未知时保留原号查询。
snString(16)条件必填系统订单号(sn 与 client_sn 至少提供一个)
client_snString(32)条件必填商户订单号(sn 与 client_sn 至少提供一个)
refund_amountString(10)是退款金额,以分为单位
operatorString(32)是操作员名称,例如 "CASHIER-01"
extendedObject否扩展参数对象;渠道专属参数按已开通能力传入。
extended.refund_modeString条件必填KPay 二维码部分退款时必填 refund;缺省或其他模式须退清剩余可退额。KPay 银行卡不支持部分退款。
📤响应关键字段
参数说明
biz_response.result_codeREFUND_SUCCESS=成功;REFUND_IN_PROGRESS=处理中;REFUND_FAIL=明确失败;REFUND_ERROR=异常待核实。
biz_response.data.order_statusREFUNDED(全额退款)/PARTIAL_REFUNDED(部分退款)
biz_response.data.net_amount剩余金额(交易总金额减去累计退款金额)
⚠️
注意: 新业务退款使用新号;相同业务保留原 refund_request_no,不要从最长订单号直接拼出超过 31 字符的退款号。
先查 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 使用原退款号查单,只有核实该次流水成功才确认退款完成;顾客到账时间另由渠道决定。

订单查询

查询当前订单状态与支付结果,用于对账与异常处理。

🔗接口信息
接口地址: POST https://api.aimt-horizon.com/upay/v2/query
签名凭证: 使用 terminal_sn + terminal_key
📥请求参数
参数类型是否必填说明
terminal_snString(32)是原交易商户下的有效终端;不能填 target_device_id。跨终端查询须保持同商户授权。
snString(16)条件必填系统订单号(优先使用;sn 与 client_sn 至少提供一个)
client_snString(32)条件必填原 tradePush.out_trade_no;与 sn 至少传一个,同时传入时保持一致。
refund_request_noString(31)否查询指定退款时填写原退款请求号;省略时通常返回订单最新交易流水,可能是退款。
📤响应关键字段
{ "result_code": "200", "biz_response": { "result_code": "SUCCESS", "data": { "sn": "7892250221234567", "client_sn": "SG20261022001", "tsn": "7892250221234568", "type": "PAYMENT", "status": "SUCCESS", "order_status": "PAID", "payway": "2", "total_amount": "100", "net_amount": "100", "subject": "Dining - Table 12", "finish_time": "1792627201000" } } }
参数说明
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。

终端结算(交班)

向支付终端推送结算(交班)指令,完成日终结算操作。

🔗接口信息
接口地址: POST https://api.aimt-horizon.com/mis/shift
签名凭证: 使用 terminal_sn + terminal_key
📥请求参数
参数类型是否必填说明
terminal_snString(32)是绑定来源系统的终端序列号
target_device_idString(20)是目标支付设备 ID,例如终端背面的 TUSN 编号
📤响应示例(指令受理)
{ "result_code": "200", "error_message": null, "error_code": null, "biz_response": { "result_code": "MIS_PUSH_SUCCESS", "error_code": null, "error_message": null } }
📤响应示例(失败)
{ "result_code": "200", "error_message": null, "error_code": null, "biz_response": { "result_code": "MIS_PUSH_FAIL", "error_code": "MIS_PUSH_FAIL", "error_message": "Push failed" } }
💡
要点:
结算操作通常在营业日结束时执行。
发起结算前,请确保当日所有交易均已处理完成。
MIS_PUSH_SUCCESS 只表示交班指令受理。本组接口未确认通用交班结果查询或汇总回调;须按设备联调确认完成,不等同资金结算到账。

交班请求示例

{
  "terminal_sn": "2101107140290972547",
  "target_device_id": "TUSN12345678"
}

在目标设备支持并开通时调用。接口未提供统一交班结果查询地址;请通过设备或已约定的渠道结果完成验收。

关单/撤销

关闭尚未完成支付的订单。当前通联/KPay 路径默认拒绝已明确为 PAID 的订单;已支付订单的资金退回应使用已开通的退款流程。关单与支付并发时仍须查单确认结果。

🔗接口信息
接口地址: POST https://api.aimt-horizon.com/mis/close
签名凭证: 使用 terminal_sn + terminal_key
📥请求参数
参数类型是否必填说明
terminal_snString(32)是终端序列号
out_trade_noString(32)是商户订单号(来自原始 tradePush 订单)
cancel_reasonString(20)是撤销原因,最多 20 个字符
target_device_idString(20)是目标支付设备 ID
cancel_notify_urlString(128)否撤销结果通知的回调地址
biz_sourceString否业务来源,默认为 "mis"
client_ipString否请求方 IP 地址
📤请求示例
{ "terminal_sn": "2101107140290972547", "out_trade_no": "SG20261022001", "cancel_reason": "Customer cancelled", "target_device_id": "TUSN12345678", "biz_source": "mis" }
📤响应示例(受理,仍需查单)
{ "result_code": "200", "error_message": null, "error_code": null, "biz_response": { "result_code": "MIS_PUSH_SUCCESS", "error_code": null, "error_message": null } }
📤响应示例(失败)
{ "result_code": "200", "error_message": null, "error_code": null, "biz_response": { "result_code": "MIS_PUSH_FAIL", "error_code": "TERMINAL_SN_UN_BIND", "error_message": "Terminal SN is unbound, push failed" } }
⚠️
注意:
先查原订单;查单后仍可能完成付款,关单提示已支付时应重新查单。未支付订单也受预撤单条件、渠道和设备能力限制;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,使用公钥验证
📥回调参数(核心字段)
参数类型说明
snString(16)系统订单号
client_snString(32)商户订单号(out_trade_no)
trade_noString(64)支付渠道订单号(支付成功时提供)
typeString流水类型:PAYMENT、REFUND、CANCEL 等;与 status 一起判断。
tsnString平台交易流水号;同一订单可对应多条流水。
client_tsnString该交易流水的外部标识;退款时用于关联原退款业务。
statusString(32)交易流水状态
order_statusString(32)当前订单状态
total_amountString(10)交易总金额
net_amountString(10)订单剩余未退原始金额;不是扣手续费后的结算净收入。
paywayString渠道支付方式编码,例如 PayNow=3001;与推单 pay_type 枚举不同。
finish_timeString(13)当前流水完成时间(Unix 毫秒);退款通知可能是退款完成时间。
subjectString(64)交易摘要
🔐验签流程
1. 保留原始请求字节,读取整个 Authorization 签名值 2. 使用环境对应的平台公钥进行 SHA256withRSA 验签 3. 通过后解析 JSON,核对订单、金额、流水类型和状态 4. 可靠保存通知,幂等处理或异步处理业务 5. 返回 HTTP 2xx,Body 为纯文本 success(无引号、无换行)
📤回调应答
success

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/activatevendor_sn + vendor_keyMD5 或 SHA256(十六进制)
/terminal/checkinterminal_sn + terminal_key请求用当前密钥;成功响应用返回的新密钥,见签到章节。
/appPush/tradePushterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
/mis/refundterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
/upay/v2/refundterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
/upay/v2/queryterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
/mis/shiftterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
/mis/closeterminal_sn + terminal_keyMD5 或 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-service
f2f1555d095c
MisTradePushController.java:45,161、MisPushApiExceptionEnumV2.java、MisServiceImpl.java:177、AllinpayServices.java:35,114。推送结果码、设备归属及通知转发范围。
upay-frontend-proxy
e1238c7
MisPushController.java:23;MisPushServiceImpl.java:109,166,273。退款参数、目标支付终端转换、client_sn 映射。
upay-gateway
f5f8dbc7e0ed
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 行为。