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/mis-refund.md.
  • English
  • MIS Refund (Device)

    Push refund instruction to payment terminal. The terminal device handles the refund operation and returns the result.

    API Information

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

    Request Parameters

    ParameterTypeRequiredDescription
    terminal_snString(32)YesTerminal SN bound to the source system
    out_trade_noString(32)YesMerchant order number (from the original tradePush)
    target_device_idString(20)YesTarget payment device ID (e.g., TUSN on the back of the terminal)
    refund_amountStringYesRefund amount in cents
    refund_request_noString(31)YesUnique ID for each new refund, up to 31 characters in the checked implementation; retain it when the outcome is unknown.
    biz_sourceString(128)YesBusiness source
    client_ipStringNoRequester IP address
    extended.refund_modeStringNoRefund mode (cancel / refund); for KPay POS only

    Request Example

    {
      "terminal_sn": "2101107140290972547",
      "out_trade_no": "SG20261022001",
      "target_device_id": "TUSN12345678",
      "refund_amount": "10",
      "refund_request_no": "SG20261022001_R001",
      "biz_source": "mis"
    }

    Response (Command Accepted)

    {
      "result_code": "200",
      "error_message": null,
      "error_code": null,
      "biz_response": {
        "result_code": "MIS_PUSH_SUCCESS",
        "error_code": null,
        "error_message": null
      }
    }

    Response Example (Failure)

    {
      "result_code": "200",
      "error_message": null,
      "error_code": null,
      "biz_response": {
        "result_code": "MIS_PUSH_FAIL",
        "error_code": "TERMINAL_SN_UN_BIND",
        "error_message": "Terminal SN is unbound, push failed"
      }
    }
    Important
    • Use a new refund_request_no for each new business refund; retain the original ID for queries and recovery.
    • out_trade_no must match the original order from tradePush.
    • MIS_PUSH_SUCCESS only acknowledges the refund command; query the original order with refund_request_no to confirm that refund.
    • Do not change the ID or switch to the server-refund API while the result is unknown. Duplicate requests are not guaranteed to replay a successful response.

    Feishu marks biz_source required while the current DTO defaults it to mis; explicitly send "mis" for compatibility. extended is a JSON object containing refund_mode, not a literal top-level key named "extended.refund_mode". KPay cancel/refund modes require the enabled device contract. The checked KPay gateway requires the full remaining refundable amount when the mode is absent or not refund; bank-card transactions require it even in refund mode.