> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # 开始接入 ## AiMT 新加坡 \{#overview} 面向新加坡金融机构、独立软件开发商(ISV)及支付服务商的推送支付接入方案。将订单推送至专用支付终端,通过 AiMT 完成支付、退款、查询、结算与撤销等业务操作。 🔗 POST /appPush/tradePush 🌐 HTTPS / JSON / UTF-8 🔐 MD5 / SHA256 签名 *** ### 方案概览 五项核心能力,覆盖支付业务全流程 | 能力 | 说明 | | ----------------------------------------------- | ------------ | | [终端激活](/zh/api/activate.md) | 一次性终端注册 | | [订单推送](/zh/api/pushorder.md) | 向支付终端推送订单 | | [退款](/zh/api/refund.md) | 退款能力及限制按渠道开通 | | [查询](/zh/api/query.md) | 实时查询订单状态 | | [回调](/zh/guide/signing-notifications.md#notify) | 异步通知交易结果 | ## 适用范围与能力 \{#scope} 适用于新加坡门店收银系统通过 AiMT 将订单推送到已开通的专用支付设备。服务端负责签名、保存订单和确认结果;收银设备负责展示与执行付款。本页覆盖调用链,不代表所有渠道、机型及固件都已开通全部能力。 文档核对日期:2026-10-22 · 地区:新加坡 · 接入协议:V2 签名 · [依据与待确认项](/zh/guide/sources.md#sources) | 任务 | 接口 | 完成判据与边界 | | ----------- | -------------------------------------------- | -------------------------------------------------------------------- | | 注册调用方 | [`/terminal/activate`](/zh/api/activate.md) | 获得并安全保存 terminal_sn / terminal_key;目标设备另外绑定。 | | 更新密钥 | [`/terminal/checkin`](/zh/api/checkin.md) | 新密钥校验并原子持久化;不替代设备注册。 | | 收款 | [`/appPush/tradePush`](/zh/api/pushorder.md) | PUSH_SUCCESS 仅表示受理;查询/验签通知确认原订单已支付。 | | 查单 | [`/upay/v2/query`](/zh/api/query.md) | 查询结果中的订单、流水类型、金额、状态一致。 | | 退款/撤销(设备路径) | [`/mis/refund`](/zh/api/mis-refund.md) | 按设备/渠道约定使用;MIS_PUSH_SUCCESS 不等于资金已退。 | | 退款(服务端路径) | [`/upay/v2/refund`](/zh/api/refund.md) | 渠道开通并具有退款权限;确认指定 refund_request_no 的结果。两种退款路径按已接入方案选择,结果未知时不能互相兜底重发。 | | 关单 | [`/mis/close`](/zh/api/close.md) | 关闭尚未完成支付的订单;处理支付与关单竞争,已支付订单按开通的退款路径处理。 | | 终端交班 | [`/mis/shift`](/zh/api/settlement.md) | 确认设备执行结果;不是资金清算、到账或账单接口。 | ### 支付方式与环境 `pay_type=1` 表示银行卡,`2` 表示扫码,`6` 表示 C 扫 B(顾客扫描商户收款码);仅选择已为商户和设备开通的值。参考枚举中的 `3` 是花呗,并非通用分期;`4/5` 是预授权。这些值的存在不构成新加坡能力承诺,预授权类型不能任意与其他类型混用,部分固件还有 2/6 映射差异。支付品牌、SGD 币种、部分退款、多次退款、撤销和预授权能力均须以开通配置验证。 联调前取得测试地址、测试商户/设备、平台公钥、测试支付介质与渠道能力清单。`https://api.aimt-horizon.com` 是已提供的新加坡接入域名,不默认代表不会真实扣款的沙箱。生产与测试凭证、公钥和回调配置分开管理。 ## 完成第一笔测试交易 \{#quickstart} [下载完整 Python 示例 ](/examples/zh/aimt_example.py) 先完成[接入准备](/zh/guide/getting-started.md#prerequisites)及[调用方激活](/zh/api/activate.md),再按此路径验证。每次只推送一个新的业务订单;运行 push 会向配置的环境提交真实 API 请求。 1. **备齐配置。** 从安全配置或环境变量读取 `AIMT_BASE_URL`、`AIMT_TERMINAL_SN`、`AIMT_TERMINAL_KEY`、`AIMT_TARGET_DEVICE_ID`、`AIMT_NOTIFY_URL`。设置同一商户内唯一的 `AIMT_ORDER_ID`(1~32 位英文/数字)。回调接收端应先按[通知规范](/zh/guide/signing-notifications.md#notify)部署。 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` 优先按平台订单号查询。不明结果按[恢复流程](/zh/guide/business.md#reliability)处理。 6. **验证退款。** 按已开通的退款路径发起一个新退款业务,记录退款号;设置 `AIMT_REFUND_REQUEST_NO` 后 query 必须定位该次退款。支付与退款各保留独立记录。 ```bash python3 aimt_example.py selftest python3 aimt_example.py push python3 aimt_example.py query ``` ### Python 3:签名、推单与查单完整示例 通过本节开头的链接下载 `aimt_example.py`。此示例仅覆盖推单/查询的普通响应验签,不覆盖激活、签到或回调接收;这些接口的密钥与验签规则见各自章节。终端异常只打印脱敏标识和状态。 :::details 完整 Python 源码 ```python title="aimt_example.py" file="/public/examples/zh/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() ``` ::: :::tip 第一次测试的通过标准 - 商户只产生一笔收款,推单、查单和通知能关联同一订单。 - 通知验签及纯文本应答正确,查询与通知不会导致重复履约。 - 仅看到设备支付成功或 `PUSH_SUCCESS` 不算通过。 ::: ## 接入准备:激活前 \{#prerequisites} 调用接口前,请先完成以下步骤 ### 提交企业资料 向技术支持提供以下信息: | 资料项 | 说明 | | ----- | ------------------------------- | | 公司名称 | 注册法定公司名称(英文;如有中文名称可一并提供) | | 公司地址 | 新加坡注册地址 | | 联系人 | 技术接入负责人的姓名 | | 联系电话 | 新加坡联系电话(+65) | | 联系邮箱 | 用于接收技术通知的企业邮箱 | | 开发技术栈 | 主要编程语言/框架,例如 Java、Python、.NET 等 | ### 获取开发参数 审核通过后,将获得: | 参数 | 说明 | | ------------ | ------ | | `vendor_sn` | 服务商序列号 | | `vendor_key` | 服务商密钥 | | `app_id` | 应用 ID | ### 商户入网与激活码 完成商户入网,生成 store_sn,获取激活码(code),规划 device_id 命名,并实现签名算法(接口调用使用 MD5,回调验签使用 RSA SHA256WithRSA)。 ## 关键术语 \{#terms} | 术语 | 说明 | | -------------------- | ------------------------------------------------------------------------------ | | **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** | 系统订单号,由平台分配的全局唯一订单标识 |