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/refund.md.
  • English
  • 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

    ParameterTypeRequiredDescription
    terminal_snString(32)YesAuthorized terminal under the original merchant; cross-store refunds also depend on permissions and channel rules.
    refund_request_noString(31)YesUnique ID of a new refund, 1-31 characters; retain it for queries while the outcome is unknown.
    snString(16)ConditionalSystem order number (one of sn or client_sn required)
    client_snString(32)ConditionalMerchant order number (one of sn or client_sn required)
    refund_amountString(10)YesRefund amount in cents
    operatorString(32)YesOperator name (e.g., "CASHIER-01")
    extendedObjectNoAn object containing channel-specific parameters for enabled capabilities.
    extended.refund_modeStringConditionalSet 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

    ParameterDescription
    biz_response.result_codeREFUND_SUCCESS=success; REFUND_IN_PROGRESS=pending; REFUND_FAIL=definite failure; REFUND_ERROR=unresolved error.
    biz_response.data.order_statusREFUNDED (full) / PARTIAL_REFUNDED (partial)
    biz_response.data.net_amountRemaining amount (total_amount minus cumulative refunds)
    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.

    {
      "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.