> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # 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 | Parameter | Type | Required | Description | | ------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `terminal_sn` | String(32) | Yes | Terminal SN bound to the source system | | `out_trade_no` | String(32) | Yes | Unique within the merchant, up to 32 bytes, ASCII letters and digits only; use the same value as client_sn later. | | `total_amount` | String(10) | Yes | Positive integer cents, at most 10 digits, e.g. SGD 1.00 = "100". Channel limits also apply. | | `trade_time` | String(13) | Yes | Current 13-digit Unix epoch milliseconds at push time; generate a current value for each call. | | `target_device_id` | String(20) | Yes | Target payment device ID (e.g., TUSN on the back of the terminal) | | `notify_url` | String(128) | Yes | Publicly reachable HTTPS payment-notification URL. See callback retry rules; they are not push-request retry rules. | | `cancel_notify_url` | String(128) | No | Cancellation-notification URL. Delivery depends on device and routing and must be verified during integration; it does not replace payment queries. | | `pay_type` | String(32) | No | Common 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. | | `remark` | String(16) | No | Order notes (e.g., table number, reference) | ## Call Example ```bash curl --request POST 'https://api.aimt-horizon.com/appPush/tradePush' \ --header 'Authorization: 2101107140290972547 ' \ --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 ```mermaid flowchart TD accTitle: Push payment workflow accDescr: The cashier creates an order and pushes it to the payment device. After the customer pays, the merchant verifies the notification and confirms the result, using queries for recovery. A["Cashier creates order in merchant system"] --> B["POST /appPush/tradePush"] B --> C["Terminal displays order and prompts for payment"] C --> D["Customer pays by QR or card"] D --> E["Result callback to notify_url"] E --> F["Verify signature, order, amount and transaction state"] F --> G["Persist event and update order idempotently"] B -. "Confirm result or recover an unknown outcome" .-> Q["POST /upay/v2/query"] Q --> F ``` `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](/guide/business.md#response-states) before updating the local order. :::warning 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 ```json { "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](/guide/testing.md#errors) for recovery.