> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # 签名与通知 ## 请求规范与签名 \{#auth-signing} ### 请求域名 ```text https://api.aimt-horizon.com ``` 新加坡接入域名由飞书接口文档确认。测试环境地址、凭证与真实扣款边界须在联调开通时单独获取,不能把此域名默认当作沙箱。 ### 请求规范 | 项目 | 规范 | | ------------ | ---------------- | | 协议 | HTTPS | | 请求方法 | POST | | Content-Type | application/json | | 编码 | UTF-8 | ### 签名方法 平台接口仅支持 JSON 格式请求。请在 HTTP 请求头中设置 `Content-Type: application/json`。 所有请求体必须使用 UTF-8 编码,响应也使用相同编码。 调用所有平台接口均需要签名验证。 签名覆盖实际发送的 UTF-8 原始字节。先生成最终 JSON,再签名;字段顺序、空格、转义或末尾换行变化均需重新计算。 Authorization 使用调用方序列号与签名;交易接口中该序列号必须与 Body 的 terminal_sn 一致。 **签名算法(V2):** 待签名内容为 HTTP 请求体原始字节与密钥直接拼接:激活用 vendor_key,其余本页业务接口用 terminal_key。 ```text sign = HEX(HASH(request_body_bytes + secret_key)) ``` 其中 HASH 支持 MD5 和 SHA256: - 默认使用 `MD5` - 也可使用 `SHA256`,增强安全性 - 通过 `Authorization-Type` 请求头指定算法(md5 或 sha256) - 省略 `Authorization-Type` 时,默认使用 md5 **签名请求头格式:** ```http Authorization: Authorization-Type: md5 (or sha256) ``` 序列号与签名之间使用一个半角空格;算法值必须小写 md5 / sha256,十六进制签名比较不区分大小写。此处是 HASH(body + key),不是 HMAC。 所有响应参数均为 JSON 格式。 按字段类型解析:result_code 与金额等常用标量为字符串;biz_response / data / extended 为对象,集合为数组,错误字段可为空或省略。 SGD 金额用新加坡分的整数字符串,例如 SGD 1.00 = "100";不用浮点数。接口本身不通过示例金额自动选择币种,需确认商户/渠道币种配置。 ### 凭证使用范围 | 适用范围 | 序列号 | 密钥 | | -------------------- | ----------- | ------------ | | `/terminal/activate` | vendor_sn | vendor_key | | 其他所有接口 | terminal_sn | terminal_key | ### 请求示例 ```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" }' ``` ### 本地签名测试向量 下例仅验证字节拼接和编码,凭证是虚构值,不可直接调用支付 API;Body 末尾没有换行。[完整示例](/zh/guide/getting-started.md#quickstart)的 selftest 使用同一 SHA256 向量。 ```text body = {"terminal_sn":"TEST_TERMINAL","client_sn":"SG_TEST_001"} secret_key = TEST_SECRET md5 = e628a48f6c61626e8074bd049a960793 sha256 = 3425ab126f49ea26ec607af9d2d2c90225db75a43b8fabd01e28580d2080d00f ``` 下面接口的 cURL 只示意报文形态,`` 必须按最终请求体实时计算;推荐先运行完整 Python 示例,避免签名与实际发送的 JSON 不一致。 ## 回调验签 \{#auth-callback} ### 回调签名验证 网关 V2 支付通知使用 SHA256withRSA;取消通知结构另见异步回调章节。请对原始请求体验签,验签通过前不处理业务。 1. 取整个 `Authorization` 头作为 RSA 签名;它不带 `terminal_sn` 前缀。 2. 读取并保留原始 UTF-8 请求字节;不要先解析再序列化。 3. 使用对应环境的平台公钥;上线前确认公钥发放与轮换流程。 4. 使用平台公钥按 SHA256withRSA 验签;通过后再解析 JSON 并核对订单与金额。 5. 可靠保存合法通知后返回 HTTP 2xx + 纯文本 `success`;无效签名不更新订单。 ### 响应签名验证 正常业务响应使用 V2 签名,验签对象是收到的原始响应字节。认证早期失败可能没有有效签名;这种响应只能用于排障,不能作为可信业务结果。 ```text 响应头: Authorization: ``` 普通交易响应用本次请求的算法与成功匹配的 terminal_key;激活响应仍用 vendor_sn / vendor_key。签到成功响应改用返回的新 terminal_key,见签到章节。 ## 异步回调通知 \{#notify} 支付平台通过 HTTP POST 向商户系统推送支付结果。必须实现回调处理,同时结合其他方式确认结果。 ### 接口信息 - **通知方向:** 支付平台 → 商户服务器 - **请求方法:** POST Content-Type: application/json - **验签方式:** RSA SHA256WithRSA;从 Authorization 请求头获取 sign,使用公钥验证 ### 回调参数(核心字段) | 参数 | 类型 | 说明 | | -------------- | ---------- | ------------------------------------------- | | `sn` | String(16) | 系统订单号 | | `client_sn` | String(32) | 商户订单号(out_trade_no) | | `trade_no` | String(64) | 支付渠道订单号(支付成功时提供) | | `type` | String | 流水类型:PAYMENT、REFUND、CANCEL 等;与 status 一起判断。 | | `tsn` | String | 平台交易流水号;同一订单可对应多条流水。 | | `client_tsn` | String | 该交易流水的外部标识;退款时用于关联原退款业务。 | | `status` | String(32) | 交易流水状态 | | `order_status` | String(32) | 当前订单状态 | | `total_amount` | String(10) | 交易总金额 | | `net_amount` | String(10) | 订单剩余未退原始金额;不是扣手续费后的结算净收入。 | | `payway` | String | 渠道支付方式编码,例如 PayNow=3001;与推单 pay_type 枚举不同。 | | `finish_time` | String(13) | 当前流水完成时间(Unix 毫秒);退款通知可能是退款完成时间。 | | `subject` | String(64) | 交易摘要 | ### 验签流程 1. 保留原始请求字节,读取整个 `Authorization` 签名值 2. 使用环境对应的平台公钥进行 SHA256withRSA 验签 3. 通过后解析 JSON,核对订单、金额、流水类型和状态 4. 可靠保存通知,幂等处理或异步处理业务 5. 返回 HTTP 2xx,Body 为纯文本 `success`(无引号、无换行) ### 回调应答 ```text success ``` HTTP 状态须为 2xx,Body 必须恰好是小写 success,不含引号、空格或换行;验签并可靠保存后再应答。 :::warning 重要 - 按流水类型、tsn 与状态实现业务幂等,并核对商户/订单范围;不能只按 sn 永久去重,否则会漏处理后续退款。 - 执行业务逻辑前必须验证签名。 - 回调与主动轮询查询应配合使用,不要仅依赖回调。 遇到冲突时按同一订单及流水重新查询核实;旧通知不得覆盖更新状态,持续不一致进入人工核对。 ::: ## 通知投递与接收实现 \{#notification-details} ### 支付通知示例 以下为虚构值的最小字段示例;真实通知为直接 JSON 对象,不包裹 `biz_response`。`tsn/type/status` 标识当前流水和状态,`client_tsn` 是该流水的外部标识,退款流水不能当成新的付款。 ```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 验签函数 使用 Node.js 标准库;`rawBody` 必须是尚未经过 JSON 中间件改写的原始 Buffer。此函数按本地 SDK 的 Base64 编码实现;上线前用目标环境的含中文通知样本验签通过,详见[核验范围](/zh/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 ``` ### 投递规则与应答 本地网关实现首次立即投递;失败后依次等待 **1、5、30、600 秒** ,最多重试四次(含首次最多五次)。非 2xx、网络失败、空 Body、带引号或换行的 `success` 都会导致重试。不要依赖永久重试;持续漏通知由查单和对账补偿。先验签并可靠保存,再快速应答,耗时业务异步处理;没有确认统一的接收超时 SLA。 ```http HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 7 success ``` ### 取消通知是不同的载荷 已核对的预撤单路径(订单尚未生成且允许预撤单)可能向 `cancel_notify_url` 发送以下结构;它没有支付通知的 `sn/type/order_status`,不能据此认定顾客已退款。取消通知覆盖范围依设备/路由而异,必须联调;`/mis/close` 可显式传入取消通知地址。 在已核对的通联/KPay 预撤单路径中,代理将请求中的 `terminal_sn` 转为目标支付终端号,网关将此值写入取消通知。同商户双终端示例:调用方为 `2101107140290972547`,目标支付终端为 `2101107140290972548`;下例返回后者。验签后按 `out_trade_no` 及已核实的商户、设备映射关联,不能强制要求通知终端号等于请求方终端号。 ```json { "terminal_sn": "2101107140290972548", "out_trade_no": "SG20261022001", "cancel_reason": "Customer cancelled", "cancel_time": "1792627201000" } ``` 使用相同的网关 RSA 验签和纯文本应答规则。按原订单及取消业务去重,并查询核实最终结果;不要要求取消通知一定具有支付流水字段。 ## 签名汇总 \{#signature-summary} 所有接口调用均采用 V2 签名机制。签名计算方式为 HEX(HASH(request_body_bytes + secret_key)),其中 HASH 支持 MD5 和 SHA256。通过 Authorization-Type 请求头指定算法,默认为 md5。 | 接口类型 | 凭证 | 算法(V2) | | --------------------------------------- | -------------------------- | -------------------------- | | /terminal/activate | vendor_sn + vendor_key | MD5 或 SHA256(十六进制) | | [/terminal/checkin](/zh/api/checkin.md) | terminal_sn + terminal_key | 请求用当前密钥;成功响应用返回的新密钥,见签到章节。 | | /appPush/tradePush | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) | | /mis/refund | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) | | /upay/v2/refund | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) | | /upay/v2/query | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) | | /mis/shift | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) | | /mis/close | terminal_sn + terminal_key | MD5 或 SHA256(十六进制) | | 异步回调通知 | 平台公钥 | RSA SHA256WithRSA |