> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Refund (Server) Initiate server-side refunds when enabled for the merchant, channel and payment method. Partial/repeated refunds, time limits and fee handling are configuration-dependent. ## API Information - **Endpoint:** POST `https://api.aimt-horizon.com/upay/v2/refund` - **Signature:** Uses terminal_sn + terminal_key - **Time Limit:** Determined by merchant and overseas channel configuration; not a universal three-month window. ## Request Parameters | Parameter | Type | Required | Description | | ---------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `terminal_sn` | String(32) | Yes | Authorized terminal under the original merchant; cross-store refunds also depend on permissions and channel rules. | | `refund_request_no` | String(31) | Yes | Unique ID of a new refund, 1-31 characters; retain it for queries while the outcome is unknown. | | `sn` | String(16) | Conditional | System order number (one of sn or client_sn required) | | `client_sn` | String(32) | Conditional | Merchant order number (one of sn or client_sn required) | | `refund_amount` | String(10) | Yes | Refund amount in cents | | `operator` | String(32) | Yes | Operator name (e.g., "CASHIER-01") | | `extended` | Object | No | An object containing channel-specific parameters for enabled capabilities. | | `extended.refund_mode` | String | Conditional | Set to refund for a KPay QR partial refund. An absent or other mode requires the full remaining refundable amount. KPay bank-card payments do not support partial refunds. | ## Response Key Fields | Parameter | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `biz_response.result_code` | REFUND_SUCCESS=success; REFUND_IN_PROGRESS=pending; REFUND_FAIL=definite failure; REFUND_ERROR=unresolved error. | | `biz_response.data.order_status` | REFUNDED (full) / PARTIAL_REFUNDED (partial) | | `biz_response.data.net_amount` | Remaining amount (total_amount minus cumulative refunds) | :::warning Important - Use a new ID for a new refund and retain it for the same operation; ensure generated IDs stay within 31 characters. - Check net_amount and serialize refunds per order locally. A balance query is not a concurrency lock. - Query with the original refund_request_no on unknown outcomes. Successful IDs may be rejected as duplicates; response replay is not guaranteed. - Fee refunds, refunded fees and customer credit timing depend on the channel, merchant agreement and active configuration. ::: ## KPay QR Partial Refund Example A new SGD 0.10 refund against a paid SGD 1.00 KPay QR order. First confirm the remaining refundable amount and that partial refunds are enabled for this channel and merchant. The body uses `sn`, or `client_sn` with the original order value when sn is unavailable, not `out_trade_no`. `extended` is a JSON object containing `refund_mode`. For KPay, an absent mode or any mode other than `refund` requires the full remaining refundable amount. KPay bank-card payments do not support partial refunds even in `refund` mode. These rules apply to both server and MIS refunds; supplying the mode is necessary but does not enable the channel capability. ```json { "terminal_sn": "2101107140290972547", "sn": "7892250221234567", "refund_request_no": "SG20261022001R001", "refund_amount": "10", "operator": "CASHIER01", "extended": { "refund_mode": "refund" } } ``` Do not submit both this and a MIS refund for the same operation. For `REFUND_IN_PROGRESS` / `REFUND_ERROR`, query the original refund ID; only confirm completion after verifying that transaction. Customer credit timing remains channel-dependent.