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 /guide/signing-notifications.md.
  • English
  • Signing & Notifications

    Request Specification & Signing

    Request Domain

    https://api.aimt-horizon.com

    The Feishu API reference confirms this Singapore endpoint. Obtain the test endpoint, credentials and charging scope separately; do not assume this URL is a sandbox.

    Request Specification

    ItemSpecification
    ProtocolHTTPS
    MethodPOST
    Content-Typeapplication/json
    EncodeUTF-8

    Signing Method

    All platform APIs only support JSON-formatted requests. Ensure Content-Type: application/json is included in the HTTP request header.

    All request bodies must use UTF-8 encoding. All responses will use the same encoding.

    All platform API calls require signature verification.

    Sign the exact UTF-8 bytes sent. Serialize JSON once before signing; changes to order, whitespace, escaping or a trailing newline require a new signature.

    Authorization contains the caller serial number and signature. For transaction APIs it must match terminal_sn in the body.

    Signature Algorithm (V2):

    Concatenate the raw HTTP body bytes with the secret: vendor_key for activation, terminal_key for the other business APIs on this page.

    sign = HEX(HASH(request_body_bytes + secret_key))

    Where HASH supports both MD5 and SHA256:

    • Use MD5 by default
    • Alternatively use SHA256 for enhanced security
    • Specify the algorithm via Authorization-Type header (md5 or sha256)
    • If Authorization-Type is omitted, defaults to md5

    Signature Header Format:

    Authorization: <terminal_sn> <sign>
    Authorization-Type: md5 (or sha256)

    Use one ASCII space between serial number and signature. Algorithm names are lowercase md5 / sha256; hex comparison is case-insensitive. This is HASH(body + key), not HMAC.

    All response parameters are in JSON format.

    Respect field types: result_code and amounts are commonly strings; biz_response / data / extended are objects, collections are arrays, and error fields may be null or absent.

    Represent SGD amounts as integer-cent strings, for example SGD 1.00 = "100", without floating-point arithmetic. Merchant/channel configuration determines currency.

    Credential Tiers

    ScopeSerial NumberSecret Key
    /terminal/activatevendor_snvendor_key
    All other APIsterminal_snterminal_key

    Request Example

    curl --request POST \
      --url https://api.aimt-horizon.com/appPush/tradePush \
      --header 'Authorization: 2101107140290972547 <sign>' \
      --header 'Authorization-Type: md5' \
      --header 'Content-Type: application/json' \
      --data '{
        "terminal_sn": "2101107140290972547",
        "out_trade_no": "SG20261022001",
        "total_amount": "100",
        "trade_time": "1792627200000",
        "target_device_id": "TUSN12345678",
        "notify_url": "https://your-system.com/api/payment/callback"
      }'

    Local Signature Test Vector

    Fictional credentials for byte/encoding verification only, not API credentials. The body has no trailing newline. The complete example uses this SHA256 vector for selftest.

    body = {"terminal_sn":"TEST_TERMINAL","client_sn":"SG_TEST_001"}
    secret_key = TEST_SECRET
    md5 = e628a48f6c61626e8074bd049a960793
    sha256 = 3425ab126f49ea26ec607af9d2d2c90225db75a43b8fabd01e28580d2080d00f

    The cURL snippets illustrate request shape; compute <sign> from the final body. Use the complete Python example first to avoid signing different JSON from what is sent.

    Callback Verification

    Callback Signature Verification

    Gateway V2 payment notifications use SHA256withRSA; cancellation payloads are described separately. Verify the raw request body before processing business data.

    1. Use the entire Authorization header as the RSA signature, without a terminal_sn prefix.
    2. Read and retain the exact UTF-8 body bytes; do not parse and reserialize before verification.
    3. Use the platform public key for the environment; confirm distribution and rotation before launch.
    4. Verify with the platform public key using SHA256withRSA, then parse JSON and validate the order and amount.
    5. After durably recording a valid notification, return HTTP 2xx and plain-text success. Invalid signatures must not update orders.

    Response Signature Verification

    Normal business responses use V2 signatures over the exact response bytes. Early authentication errors may lack a valid signature; treat them as diagnostics, not trusted business outcomes.

    Response Header:
    Authorization: <terminal_sn> <response_sign>

    Use the request algorithm and matched terminal_key for ordinary responses. Activation responses use vendor_sn / vendor_key. A successful check-in response uses the newly returned terminal_key.

    Callback Notification

    The payment platform pushes payment results to the merchant system via HTTP POST. Must implement, but should not be the sole method of result confirmation.

    API Information

    • Direction: Payment Platform → Merchant Server
    • Method: POST Content-Type: application/json
    • Verification: RSA SHA256WithRSA — obtain sign from Header Authorization, verify with public key

    Callback Parameters (Core)

    ParameterTypeDescription
    snString(16)System order number
    client_snString(32)Merchant order number (out_trade_no)
    trade_noString(64)Payment channel order number (present when paid)
    typeStringTransaction type: PAYMENT, REFUND, CANCEL, etc.; interpret together with status.
    tsnStringPlatform transaction ID; one order may have multiple transactions.
    client_tsnStringExternal transaction identifier; use it to associate the refund operation.
    statusString(32)Transaction flow status
    order_statusString(32)Current order status
    total_amountString(10)Transaction total amount
    net_amountString(10)Remaining original amount after refunds, not settlement income net of fees.
    paywayStringPayment method code, e.g. PayNow=3001; distinct from the push request pay_type enum.
    finish_timeString(13)Completion time of this transaction in Unix milliseconds; may refer to a refund.
    subjectString(64)Transaction summary

    Verification Flow

    1. Retain raw body bytes and the full Authorization signature
    2. Verify SHA256withRSA using the environment public key
    3. Parse JSON and check order, amount, transaction type and state
    4. Durably record the event; process business effects idempotently
    5. Return HTTP 2xx with plain-text success (no quotes/newline)

    Required Response

    success

    Return HTTP 2xx with exactly lowercase success, without quotes, spaces or newline, after verification and durable storage.

    Critical
    • Make effects idempotent by transaction type, tsn and state within the merchant/order scope; permanent deduplication by sn alone would drop later refunds.
    • Never skip signature verification before processing business logic.
    • Use callbacks alongside proactive query polling — never rely on callbacks alone. Requery the same order and transaction on conflicts. Do not overwrite newer state with an old notification; escalate persistent inconsistencies.

    Notification Delivery and Handling

    Payment Notification Example

    This is a minimal example with fictional values. The real payload is a direct JSON object, without a biz_response wrapper. tsn/type/status identify the transaction and state; client_tsn is its external identifier. A refund event is not a new payment.

    {
      "sn": "7892250221234567",
      "client_sn": "SG20261022001",
      "tsn": "7892250221234568",
      "client_tsn": "SG20261022001",
      "type": "PAYMENT",
      "status": "SUCCESS",
      "order_status": "PAID",
      "total_amount": "100",
      "net_amount": "100",
      "payway": "3001",
      "finish_time": "1792627201000"
    }

    Node.js Verification Function

    Uses the Node.js standard library. rawBody must be the original Buffer before JSON middleware modifies it. This function uses the Base64 encoding found in the local SDK; validate an authentic target-environment notification with Chinese text before launch. See verification scope.

    const { verify } = require("node:crypto");
    
    function verifyNotification(rawBody, authorization, publicKeyPem) {
        if (!Buffer.isBuffer(rawBody) || !authorization) return false;
        try {
            return verify(
                "RSA-SHA256",
                rawBody,
                publicKeyPem,
                Buffer.from(authorization, "base64")
            );
        } catch {
            return false;
        }
    }
    // Read raw bytes before any JSON middleware.
    // Parse JSON only after verification succeeds.
    // Persist the valid event before responding with:
    // HTTP 200, Content-Type: text/plain, body exactly: success

    Delivery and Acknowledgment

    The checked gateway sends immediately, then retries after 1, 5, 30 and 600 seconds , at most four retries (five total attempts). Non-2xx, network failure, empty bodies, or quoted/newline-terminated success trigger retries. Delivery is not indefinite; compensate with queries and reconciliation. Verify and durably store first, acknowledge promptly, then perform slower business work asynchronously. No universal receiver timeout SLA is confirmed.

    HTTP/1.1 200 OK
    Content-Type: text/plain
    Content-Length: 7
    
    success

    Cancellation Has a Different Payload

    The verified pre-cancel path, when no order exists and pre-cancel is allowed, can send the following payload to cancel_notify_url. It has no payment sn/type/order_status and does not prove that funds were refunded. Delivery scope depends on device/routing and must be tested. /mis/close accepts an explicit cancellation URL.

    In the checked Allinpay/KPay pre-cancel route, the proxy replaces the request terminal_sn with the target payment terminal ID, which the gateway includes in the notification. In this example, the caller is 2101107140290972547 and the target payment terminal under the same merchant is 2101107140290972548; the payload contains the latter. After signature verification, correlate out_trade_no using verified merchant/device mappings. Do not require the notification terminal ID to equal the caller ID.

    {
      "terminal_sn": "2101107140290972548",
      "out_trade_no": "SG20261022001",
      "cancel_reason": "Customer cancelled",
      "cancel_time": "1792627201000"
    }

    Apply the gateway RSA verification and plain-text acknowledgment rules. Deduplicate the cancellation operation within the original order and query the final outcome. Do not require cancellation events to contain payment transaction fields.

    Signature Summary

    All API calls use the V2 signing mechanism. The signature is computed as HEX(HASH(request_body_bytes + secret_key)), where HASH supports both MD5 and SHA256. Specify the algorithm via the Authorization-Type header (defaults to md5).

    API TypeCredentialsAlgorithm (V2)
    /terminal/activatevendor_sn + vendor_keyMD5 or SHA256 (HEX)
    /terminal/checkinterminal_sn + terminal_keyCurrent key for requests; newly returned key for successful responses. See Check-in.
    /appPush/tradePushterminal_sn + terminal_keyMD5 or SHA256 (HEX)
    /mis/refundterminal_sn + terminal_keyMD5 or SHA256 (HEX)
    /upay/v2/refundterminal_sn + terminal_keyMD5 or SHA256 (HEX)
    /upay/v2/queryterminal_sn + terminal_keyMD5 or SHA256 (HEX)
    /mis/shiftterminal_sn + terminal_keyMD5 or SHA256 (HEX)
    /mis/closeterminal_sn + terminal_keyMD5 or SHA256 (HEX)
    Callback NotificationPlatform Public KeyRSA SHA256WithRSA