For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/getting-started.md.
  • English
  • Getting Started

    AiMT Singapore

    Push payment integration for financial institutions, independent software vendors (ISVs), and payment service providers in Singapore. Push orders to dedicated payment terminals and integrate payment, refund, query, settlement, and cancellation operations with AiMT.

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

    Solution Overview

    Five core capabilities enabling end-to-end payment operations

    CapabilityDescription
    ActivationOne-time terminal registration
    Push OrderPush orders to payment terminals
    RefundRefund capabilities depend on the enabled channel
    QueryReal-time status lookup
    CallbackAsync result notification

    Scope and Capabilities

    For Singapore checkout systems pushing orders to enabled payment devices through AiMT. Your server signs requests, stores orders and confirms outcomes; the payment device displays and executes payments. API availability does not imply every channel, device or firmware supports every capability.

    Checked: 2026-10-22 · Region: Singapore · Protocol: V2 signing · Sources and open items

    TaskAPICompletion and Limits
    Register caller/terminal/activateSecurely store terminal_sn / terminal_key. Bind the payment device separately.
    Rotate key/terminal/checkinValidate and atomically persist the new key.
    Collect payment/appPush/tradePushPUSH_SUCCESS acknowledges acceptance; confirm payment by query or verified notification.
    Query/upay/v2/queryMatch order, transaction type, amount and state.
    Device refund/reversal/mis/refundDevice/channel-dependent; MIS_PUSH_SUCCESS does not confirm refunded funds.
    Server refund/upay/v2/refundRequires channel capability and permission. Confirm the specific refund_request_no. Choose the enabled refund route; do not switch routes to retry an unknown outcome.
    Close order/mis/closeClose an unpaid order and handle races with payment. Use the enabled refund route for paid orders.
    Device shift/mis/shiftConfirm execution on the device; this is not fund settlement or a statement API.

    Payment Methods and Environments

    pay_type=1 is bank card, 2 is QR and 6 is customer-scans-merchant QR (C-scan-B). Use only enabled values. Reference value 3 is Huabei, not generic instalments; 4/5 are preauthorization. These values do not establish Singapore availability. Preauthorization cannot be freely combined with other types, and some firmware has different 2/6 mappings. Verify brands, SGD configuration, partial/repeated refunds, reversals and preauthorization for the actual merchant and device.

    Obtain the test endpoint, merchant/device, platform public key, payment instruments and capability list before testing. The supplied Singapore endpoint https://api.aimt-horizon.com must not be assumed to be a non-charging sandbox. Separate test and production credentials, public keys and callback configuration.

    Complete a First Test Payment

    Download Python example

    Complete setup and caller activation first. Push each new business order once. Running push submits an actual API request to the configured environment.

    1. Configure. Load AIMT_BASE_URL, AIMT_TERMINAL_SN, AIMT_TERMINAL_KEY, AIMT_TARGET_DEVICE_ID and AIMT_NOTIFY_URL from secure configuration/environment variables. Set AIMT_ORDER_ID, unique within the merchant and 1-32 ASCII letters/digits. Deploy the notification handler first.
    2. Confirm testing scope. Verify the test merchant, SGD, device and enabled pay_type=1,2,6 before setting AIMT_TEST_CONFIRMED=1. The example submits "100", SGD 1.00. This local safeguard does not turn production into a sandbox.
    3. Run the signature self-test, then push once. The Python 3 example uses only the standard library. Self-test needs no network. Expect result_code="200" and biz_response.result_code="PUSH_SUCCESS"; do not fulfill yet.
    4. Pay on the device. Check the amount and order. Retain device evidence, await the server notification and run query with the same AIMT_ORDER_ID.
    5. Confirm. Match client_sn, amount and PAYMENT / SUCCESS / PAID; persist sn and tsn. Set AIMT_ORDER_SN for subsequent queries by platform ID. Follow recovery rules for unknown outcomes.
    6. Verify refunds. Use the enabled refund route and retain the refund ID. Set AIMT_REFUND_REQUEST_NO and query that specific refund. Keep payment and refund records separate.
    python3 aimt_example.py selftest
    python3 aimt_example.py push
    python3 aimt_example.py query

    Python 3: Complete Signing, Push and Query Example

    Download aimt_example.py using the link at the start of this section. This example verifies ordinary push/query responses only, not activation, check-in or inbound notifications; those have separate rules. Output is limited to redacted identifiers and states.

    Complete Python Source
    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()
    
    Pass Criteria
    • One collection only; push, query and notification identify the same order.
    • Notification verification and the plain-text acknowledgment work; query and notification do not duplicate fulfillment.
    • A device success screen or PUSH_SUCCESS alone is insufficient.

    Prerequisites — Before Activation

    Complete these steps before calling any API

    Submit Business Information

    Provide the following to technical support:

    FieldDescription
    Company NameRegistered legal company name (English; Chinese name if applicable)
    Company AddressRegistered address in Singapore
    Contact PersonTechnical integration lead name
    Contact PhoneSingapore contact number (+65)
    Contact EmailCorporate email for technical notifications
    Development StackPrimary programming language/framework (Java, Python, .NET, etc.)

    Obtain Developer Parameters

    After approval, you will receive:

    ParameterDescription
    vendor_snService provider serial number
    vendor_keyService provider secret key
    app_idApplication ID

    Merchant Onboarding & Activation Code

    Onboard merchants, generate store_sn, obtain activation codes (code), plan device_id naming, and implement signature algorithms (MD5 for API calls, RSA SHA256WithRSA for callback verification).

    Key Terminology

    TermDescription
    vendor_snService provider serial number — unique identifier for the financial institution/ISV
    vendor_keyService provider secret key — used for activation API signing
    app_idApplication ID — distinguishes different business applications
    codeActivation code issued for a store and application. Expiry, replacement and reactivation rules follow the issued configuration.
    device_idStable identifier of the calling ISV system used for activation; manage it separately from the target payment device.
    terminal_snIn a request, terminal_sn identifies the API caller and is obtained through activation; it is not the target device TUSN. In cancellation notifications, the same field can identify the target payment terminal; see notifications.
    terminal_keyTerminal secret key — assigned after activation; used for transaction API signing
    target_device_idTarget payment device ID — e.g., MT919 terminal TUSN number scanned at setup
    out_trade_noMerchant order ID, unique within the merchant; maps to client_sn for query and server refunds. A network retry must not create a new business order ID.
    snSystem order number — globally unique order identifier assigned by the platform