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/query.md.
  • English
  • Query

    Query current order status and payment results. The essential tool for reconciliation and exception handling.

    API Information

    • Endpoint: POST https://api.aimt-horizon.com/upay/v2/query
    • Signature: Uses terminal_sn + terminal_key

    Request Parameters

    ParameterTypeRequiredDescription
    terminal_snString(32)YesValid terminal under the original merchant, not target_device_id. Cross-terminal queries require authorization under that merchant.
    snString(16)ConditionalSystem order number (preferred lookup; one of sn or client_sn required)
    client_snString(32)ConditionalOriginal tradePush.out_trade_no; provide sn or client_sn, and keep them consistent if both are provided.
    refund_request_noString(31)NoProvide the original refund ID to query that refund. Without it, the latest transaction may be returned, including a refund.

    Response Key Fields

    {
      "result_code": "200",
      "biz_response": {
        "result_code": "SUCCESS",
        "data": {
          "sn": "7892250221234567",
          "client_sn": "SG20261022001",
          "tsn": "7892250221234568",
          "type": "PAYMENT",
          "status": "SUCCESS",
          "order_status": "PAID",
          "payway": "2",
          "total_amount": "100",
          "net_amount": "100",
          "subject": "Dining - Table 12",
          "finish_time": "1792627201000"
        }
      }
    }
    ParameterDescription
    typeTransaction type: PAYMENT, REFUND, CANCEL, etc.; interpret together with status.
    tsnPlatform transaction ID; one order may have multiple transactions.
    order_statusAggregate order state; see Response and State Handling, including pending/error payment, refund and cancellation states.
    statusCurrent transaction state, interpreted with type; SUCCESS can refer to a refund as well as a payment.
    total_amountOriginal transaction amount
    net_amountRemaining amount (total_amount minus refunds)
    finish_timeCompletion time of the returned transaction in Unix milliseconds; may be refund completion time and may be absent while pending.
    When to call Query
    • 1. Post-push confirmation: After pushing an order, query to confirm payment result.
    • 2. Unknown payment status: Network timeout or exception — query to determine the true state.
    • 3. Post-refund confirmation: Verify refund result after calling the refund API.
    • 4. Prevent single-sided transactions: Provide a manual query button for operators.

    Query by Merchant Order ID

    {
      "terminal_sn": "2101107140290972547",
      "client_sn": "SG20261022001"
    }

    Prefer sn instead of client_sn once available. Use a valid caller under the original merchant. Wrong ownership, no payment order yet or permission errors can all cause a missing result; none authorizes another collection.

    Example: Query Succeeded and Payment Succeeded

    {
      "result_code": "200",
      "biz_response": {
        "result_code": "SUCCESS",
        "data": {
          "sn": "7892250221234567",
          "client_sn": "SG20261022001",
          "tsn": "7892250221234568",
          "type": "PAYMENT",
          "status": "SUCCESS",
          "order_status": "PAID",
          "total_amount": "100",
          "net_amount": "100"
        }
      }
    }

    A successful query may also return pending or failed transaction states. Follow the four-layer rules. Add the original refund_request_no to query a specific refund and expect type=REFUND, not PAYMENT.