For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/api/mis-refund.md.
  • 简体中文
  • MIS 退款(设备端)

    向支付终端推送退款指令,由终端设备执行退款操作并返回结果。

    接口信息

    • 接口地址: POST https://api.aimt-horizon.com/mis/refund
    • 签名凭证: 使用 terminal_sn + terminal_key

    请求参数

    参数类型是否必填说明
    terminal_snString(32)是绑定来源系统的终端序列号
    out_trade_noString(32)是商户订单号(来自原始 tradePush 订单)
    target_device_idString(20)是目标支付设备 ID,例如终端背面的 TUSN 编号
    refund_amountString是退款金额,以分为单位
    refund_request_noString(31)是每个新退款业务的唯一请求号,按当前实现限制最多 31 个字符;结果未知时保留原号。
    biz_sourceString(128)是业务来源
    client_ipString否请求方 IP 地址
    extended.refund_modeString否退款模式(cancel / refund),仅适用于 KPay POS

    请求示例

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

    响应示例(指令受理)

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

    响应示例(失败)

    {
      "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"
      }
    }
    注意
    • 每个新退款业务使用新的 refund_request_no;同一退款查询或排障使用原号。
    • out_trade_no 必须与原始 tradePush 订单一致。
    • MIS_PUSH_SUCCESS 只表示退款指令受理;通过查询原订单并携带 refund_request_no 确认该次退款。
    • 结果未知时不要换号或切换到服务端退款再次提交;重复请求不承诺返回同一成功结果。

    biz_source 在飞书参数表标为必填、当前 DTO 默认是 mis;为保持接入兼容,建议显式发送 "mis"。extended 是 JSON 对象,refund_mode 是其中的字段,不是名为 "extended.refund_mode" 的顶层字符串键。KPay 的 cancel/refund 模式必须按已开通设备约定使用。已核对的 KPay 网关规则:模式缺省或不为 refund 时须退清剩余可退金额;银行卡即使采用 refund 模式也不支持部分退款。