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/refund.md.
  • 简体中文
  • 退款(服务端)

    在商户、渠道和支付方式允许时从服务端发起退款。部分退款、多次退款、可退期限和手续费处理均受配置约束。

    接口信息

    • 接口地址: POST https://api.aimt-horizon.com/upay/v2/refund
    • 签名凭证: 使用 terminal_sn + terminal_key
    • 时间限制: 按商户与海外渠道配置;不是统一的“支付完成后 3 个月”。

    请求参数

    参数类型是否必填说明
    terminal_snString(32)是原交易商户下的授权终端;跨门店退款还受权限与渠道规则限制。
    refund_request_noString(31)是新退款业务的唯一请求号,1~31 个字符;同一退款结果未知时保留原号查询。
    snString(16)条件必填系统订单号(sn 与 client_sn 至少提供一个)
    client_snString(32)条件必填商户订单号(sn 与 client_sn 至少提供一个)
    refund_amountString(10)是退款金额,以分为单位
    operatorString(32)是操作员名称,例如 "CASHIER-01"
    extendedObject否扩展参数对象;渠道专属参数按已开通能力传入。
    extended.refund_modeString条件必填KPay 二维码部分退款时必填 refund;缺省或其他模式须退清剩余可退额。KPay 银行卡不支持部分退款。

    响应关键字段

    参数说明
    biz_response.result_codeREFUND_SUCCESS=成功;REFUND_IN_PROGRESS=处理中;REFUND_FAIL=明确失败;REFUND_ERROR=异常待核实。
    biz_response.data.order_statusREFUNDED(全额退款)/PARTIAL_REFUNDED(部分退款)
    biz_response.data.net_amount剩余金额(交易总金额减去累计退款金额)
    注意
    • 新业务退款使用新号;相同业务保留原 refund_request_no,不要从最长订单号直接拼出超过 31 字符的退款号。
    • 先查 net_amount 并在本地串行化同单退款;查询余额不是并发锁,不能据此保证另一个请求未占用可退额。
    • 结果未知时带原 refund_request_no 查单;已成功退款号可能报重复,不把重放成功作为幂等契约。
    • 手续费是否退还、退还金额与顾客到账时间以渠道、商户合同和实际配置为准。

    KPay 二维码部分退款示例

    下面对已支付的 SGD 1.00 KPay 二维码订单发起 SGD 0.10 的新退款;先确认剩余可退金额及该渠道、商户已开通部分退款。请求体不使用 out_trade_no,未获得 sn 时可改传同值的 client_sn。

    extended 是 JSON 对象,refund_mode 是其内部字段。KPay 模式缺省或不为 refund 时须退清剩余可退额;KPay 银行卡即使采用 refund 也不支持部分退款。此约束同时适用于服务端和 MIS 退款;传入该模式只是必要条件,不代表渠道能力已开通。

    {
      "terminal_sn": "2101107140290972547",
      "sn": "7892250221234567",
      "refund_request_no": "SG20261022001R001",
      "refund_amount": "10",
      "operator": "CASHIER01",
      "extended": {
        "refund_mode": "refund"
      }
    }

    不要将该示例和 MIS 退款都发送给同一业务。对 REFUND_IN_PROGRESS / REFUND_ERROR 使用原退款号查单,只有核实该次流水成功才确认退款完成;顾客到账时间另由渠道决定。