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 /api/pushorder.md.
  • English
  • Push Order

    Push orders from the merchant system to dedicated payment terminals (e.g., supported P3, MT919, and other devices). Supports QR scanning and card payments.

    API Information

    • Endpoint: POST https://api.aimt-horizon.com/appPush/tradePush
    • Signature: Uses terminal_sn + terminal_key

    Request Parameters

    ParameterTypeRequiredDescription
    terminal_snString(32)YesTerminal SN bound to the source system
    out_trade_noString(32)YesUnique within the merchant, up to 32 bytes, ASCII letters and digits only; use the same value as client_sn later.
    total_amountString(10)YesPositive integer cents, at most 10 digits, e.g. SGD 1.00 = "100". Channel limits also apply.
    trade_timeString(13)YesCurrent 13-digit Unix epoch milliseconds at push time; generate a current value for each call.
    target_device_idString(20)YesTarget payment device ID (e.g., TUSN on the back of the terminal)
    notify_urlString(128)YesPublicly reachable HTTPS payment-notification URL. See callback retry rules; they are not push-request retry rules.
    cancel_notify_urlString(128)NoCancellation-notification URL. Delivery depends on device and routing and must be verified during integration; it does not replace payment queries.
    pay_typeString(32)NoCommon values: 1=bank card, 2=QR, 6=customer scans the merchant QR code (C-scan-B); separate multiple values with commas, e.g. 1,2,6. Other enum values do not imply Singapore availability; see capability limits.
    remarkString(16)NoOrder notes (e.g., table number, reference)

    Call Example

    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"
    }'

    Business Flow

    PUSH_SUCCESS only acknowledges acceptance; it does not prove that the device displayed the order or that payment succeeded. Apply the response and state rules before updating the local order.

    Key Rules
    • out_trade_no maps to client_sn for query/server refunds and is unique within the merchant. PUSH_SUCCESS normally does not return sn.
    • target_device_id must be pre-registered (scan the TUSN barcode on the terminal).
    • After PUSH_SUCCESS, wait for payment and query. On timeout query the original order; do not reuse notification delays as an automatic push retry schedule.
    • Always pair with the Query API for proactive status confirmation — do not rely solely on callbacks.

    Acceptance Response

    {
      "result_code": "200",
      "biz_response": {
        "result_code": "PUSH_SUCCESS"
      }
    }

    Error fields may be null or omitted. This response normally has no sn and does not prove device display or payment. Keep the original out_trade_no for queries; see errors for recovery.