> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Getting Started ## AiMT Singapore \{#overview} 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 | Capability | Description | | -------------------------------------------------- | ------------------------------------------------- | | [Activation](/api/activate.md) | One-time terminal registration | | [Push Order](/api/pushorder.md) | Push orders to payment terminals | | [Refund](/api/refund.md) | Refund capabilities depend on the enabled channel | | [Query](/api/query.md) | Real-time status lookup | | [Callback](/guide/signing-notifications.md#notify) | Async result notification | ## Scope and Capabilities \{#scope} 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](/guide/sources.md#sources) | Task | API | Completion and Limits | | ---------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Register caller | [`/terminal/activate`](/api/activate.md) | Securely store terminal_sn / terminal_key. Bind the payment device separately. | | Rotate key | [`/terminal/checkin`](/api/checkin.md) | Validate and atomically persist the new key. | | Collect payment | [`/appPush/tradePush`](/api/pushorder.md) | PUSH_SUCCESS acknowledges acceptance; confirm payment by query or verified notification. | | Query | [`/upay/v2/query`](/api/query.md) | Match order, transaction type, amount and state. | | Device refund/reversal | [`/mis/refund`](/api/mis-refund.md) | Device/channel-dependent; MIS_PUSH_SUCCESS does not confirm refunded funds. | | Server refund | [`/upay/v2/refund`](/api/refund.md) | Requires 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/close`](/api/close.md) | Close an unpaid order and handle races with payment. Use the enabled refund route for paid orders. | | Device shift | [`/mis/shift`](/api/settlement.md) | Confirm 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 \{#quickstart} [Download Python example ](/examples/en/aimt_example.py) Complete [setup](/guide/getting-started.md#prerequisites) and [caller activation](/api/activate.md) 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](/guide/signing-notifications.md#notify) 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](/guide/business.md#reliability) 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. ```bash 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. :::details Complete Python Source ```python title="aimt_example.py" file="/public/examples/en/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 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 \{#prerequisites} Complete these steps before calling any API ### Submit Business Information Provide the following to technical support: | Field | Description | | ----------------- | ------------------------------------------------------------------- | | Company Name | Registered legal company name (English; Chinese name if applicable) | | Company Address | Registered address in Singapore | | Contact Person | Technical integration lead name | | Contact Phone | Singapore contact number (+65) | | Contact Email | Corporate email for technical notifications | | Development Stack | Primary programming language/framework (Java, Python, .NET, etc.) | ### Obtain Developer Parameters After approval, you will receive: | Parameter | Description | | ------------ | ------------------------------ | | `vendor_sn` | Service provider serial number | | `vendor_key` | Service provider secret key | | `app_id` | Application 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 \{#terms} | Term | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **vendor_sn** | Service provider serial number โ€” unique identifier for the financial institution/ISV | | **vendor_key** | Service provider secret key โ€” used for activation API signing | | **app_id** | Application ID โ€” distinguishes different business applications | | **code** | Activation code issued for a store and application. Expiry, replacement and reactivation rules follow the issued configuration. | | **device_id** | Stable identifier of the calling ISV system used for activation; manage it separately from the target payment device. | | **terminal_sn** | In 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_key** | Terminal secret key โ€” assigned after activation; used for transaction API signing | | **target_device_id** | Target payment device ID โ€” e.g., MT919 terminal TUSN number scanned at setup | | **out_trade_no** | Merchant 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. | | **sn** | System order number โ€” globally unique order identifier assigned by the platform |