For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/getting-started.md.
  • 简体中文
  • 开始接入

    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 是已提供的新加坡接入域名,不默认代表不会真实扣款的沙箱。生产与测试凭证、公钥和回调配置分开管理。

    完成第一笔测试交易

    下载完整 Python 示例

    先完成接入准备及调用方激活,再按此路径验证。每次只推送一个新的业务订单;运行 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。此示例仅覆盖推单/查询的普通响应验签,不覆盖激活、签到或回调接收;这些接口的密钥与验签规则见各自章节。终端异常只打印脱敏标识和状态。

    完整 Python 源码
    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 不算通过。

    接入准备:激活前

    调用接口前,请先完成以下步骤

    提交企业资料

    向技术支持提供以下信息:

    资料项说明
    公司名称注册法定公司名称(英文;如有中文名称可一并提供)
    公司地址新加坡注册地址
    联系人技术接入负责人的姓名
    联系电话新加坡联系电话(+65)
    联系邮箱用于接收技术通知的企业邮箱
    开发技术栈主要编程语言/框架,例如 Java、Python、.NET 等

    获取开发参数

    审核通过后,将获得:

    参数说明
    vendor_sn服务商序列号
    vendor_key服务商密钥
    app_id应用 ID

    商户入网与激活码

    完成商户入网,生成 store_sn,获取激活码(code),规划 device_id 命名,并实现签名算法(接口调用使用 MD5,回调验签使用 RSA SHA256WithRSA)。

    关键术语

    术语说明
    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系统订单号,由平台分配的全局唯一订单标识