> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Signing & Notifications ## Request Specification & Signing \{#auth-signing} ### Request Domain ```text 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 | Item | Specification | | ------------ | ---------------- | | Protocol | HTTPS | | Method | POST | | Content-Type | application/json | | Encode | UTF-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. ```text 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:** ```http Authorization: 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 | Scope | Serial Number | Secret Key | | -------------------- | ------------- | ------------ | | `/terminal/activate` | vendor_sn | vendor_key | | All other APIs | terminal_sn | terminal_key | ### Request Example ```bash curl --request POST \ --url https://api.aimt-horizon.com/appPush/tradePush \ --header 'Authorization: 2101107140290972547 ' \ --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](/guide/getting-started.md#quickstart) uses this SHA256 vector for selftest. ```text 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 `` from the final body. Use the complete Python example first to avoid signing different JSON from what is sent. ## Callback Verification \{#auth-callback} ### 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. ```text Response Header: Authorization: ``` 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 \{#notify} 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) | Parameter | Type | Description | | -------------- | ---------- | ------------------------------------------------------------------------------------ | | `sn` | String(16) | System order number | | `client_sn` | String(32) | Merchant order number (out_trade_no) | | `trade_no` | String(64) | Payment channel order number (present when paid) | | `type` | String | Transaction type: PAYMENT, REFUND, CANCEL, etc.; interpret together with status. | | `tsn` | String | Platform transaction ID; one order may have multiple transactions. | | `client_tsn` | String | External transaction identifier; use it to associate the refund operation. | | `status` | String(32) | Transaction flow status | | `order_status` | String(32) | Current order status | | `total_amount` | String(10) | Transaction total amount | | `net_amount` | String(10) | Remaining original amount after refunds, not settlement income net of fees. | | `payway` | String | Payment method code, e.g. PayNow=3001; distinct from the push request pay_type enum. | | `finish_time` | String(13) | Completion time of this transaction in Unix milliseconds; may refer to a refund. | | `subject` | String(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 ```text success ``` Return HTTP 2xx with exactly lowercase success, without quotes, spaces or newline, after verification and durable storage. :::warning 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 \{#notification-details} ### 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. ```json { "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](/guide/sources.md#sources). ```javascript 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 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. ```json { "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 \{#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 Type | Credentials | Algorithm (V2) | | ------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------ | | /terminal/activate | vendor_sn + vendor_key | MD5 or SHA256 (HEX) | | [/terminal/checkin](/api/checkin.md) | terminal_sn + terminal_key | Current key for requests; newly returned key for successful responses. See Check-in. | | /appPush/tradePush | terminal_sn + terminal_key | MD5 or SHA256 (HEX) | | /mis/refund | terminal_sn + terminal_key | MD5 or SHA256 (HEX) | | /upay/v2/refund | terminal_sn + terminal_key | MD5 or SHA256 (HEX) | | /upay/v2/query | terminal_sn + terminal_key | MD5 or SHA256 (HEX) | | /mis/shift | terminal_sn + terminal_key | MD5 or SHA256 (HEX) | | /mis/close | terminal_sn + terminal_key | MD5 or SHA256 (HEX) | | Callback Notification | Platform Public Key | RSA SHA256WithRSA |