> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # 退款(服务端) 在商户、渠道和支付方式允许时从服务端发起退款。部分退款、多次退款、可退期限和手续费处理均受配置约束。 ## 接口信息 - **接口地址:** POST `https://api.aimt-horizon.com/upay/v2/refund` - **签名凭证:** 使用 terminal_sn + terminal_key - **时间限制:** 按商户与海外渠道配置;不是统一的“支付完成后 3 个月”。 ## 请求参数 | 参数 | 类型 | 是否必填 | 说明 | | ---------------------- | ---------- | ---- | ------------------------------------------------------- | | `terminal_sn` | String(32) | 是 | 原交易商户下的授权终端;跨门店退款还受权限与渠道规则限制。 | | `refund_request_no` | String(31) | 是 | 新退款业务的唯一请求号,1~31 个字符;同一退款结果未知时保留原号查询。 | | `sn` | String(16) | 条件必填 | 系统订单号(sn 与 client_sn 至少提供一个) | | `client_sn` | String(32) | 条件必填 | 商户订单号(sn 与 client_sn 至少提供一个) | | `refund_amount` | String(10) | 是 | 退款金额,以分为单位 | | `operator` | String(32) | 是 | 操作员名称,例如 "CASHIER-01" | | `extended` | Object | 否 | 扩展参数对象;渠道专属参数按已开通能力传入。 | | `extended.refund_mode` | String | 条件必填 | KPay 二维码部分退款时必填 refund;缺省或其他模式须退清剩余可退额。KPay 银行卡不支持部分退款。 | ## 响应关键字段 | 参数 | 说明 | | -------------------------------- | ----------------------------------------------------------------------------- | | `biz_response.result_code` | REFUND_SUCCESS=成功;REFUND_IN_PROGRESS=处理中;REFUND_FAIL=明确失败;REFUND_ERROR=异常待核实。 | | `biz_response.data.order_status` | REFUNDED(全额退款)/PARTIAL_REFUNDED(部分退款) | | `biz_response.data.net_amount` | 剩余金额(交易总金额减去累计退款金额) | :::warning 注意 - 新业务退款使用新号;相同业务保留原 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 退款;传入该模式只是必要条件,不代表渠道能力已开通。 ```json { "terminal_sn": "2101107140290972547", "sn": "7892250221234567", "refund_request_no": "SG20261022001R001", "refund_amount": "10", "operator": "CASHIER01", "extended": { "refund_mode": "refund" } } ``` 不要将该示例和 MIS 退款都发送给同一业务。对 `REFUND_IN_PROGRESS` / `REFUND_ERROR` 使用原退款号查单,只有核实该次流水成功才确认退款完成;顾客到账时间另由渠道决定。