For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/signing-notifications.md.
  • 简体中文
  • 签名与通知

    请求规范与签名

    请求域名

    https://api.aimt-horizon.com

    新加坡接入域名由飞书接口文档确认。测试环境地址、凭证与真实扣款边界须在联调开通时单独获取,不能把此域名默认当作沙箱。

    请求规范

    项目规范
    协议HTTPS
    请求方法POST
    Content-Typeapplication/json
    编码UTF-8

    签名方法

    平台接口仅支持 JSON 格式请求。请在 HTTP 请求头中设置 Content-Type: application/json。

    所有请求体必须使用 UTF-8 编码,响应也使用相同编码。

    调用所有平台接口均需要签名验证。

    签名覆盖实际发送的 UTF-8 原始字节。先生成最终 JSON,再签名;字段顺序、空格、转义或末尾换行变化均需重新计算。

    Authorization 使用调用方序列号与签名;交易接口中该序列号必须与 Body 的 terminal_sn 一致。

    签名算法(V2):

    待签名内容为 HTTP 请求体原始字节与密钥直接拼接:激活用 vendor_key,其余本页业务接口用 terminal_key。

    sign = HEX(HASH(request_body_bytes + secret_key))

    其中 HASH 支持 MD5 和 SHA256:

    • 默认使用 MD5
    • 也可使用 SHA256,增强安全性
    • 通过 Authorization-Type 请求头指定算法(md5 或 sha256)
    • 省略 Authorization-Type 时,默认使用 md5

    签名请求头格式:

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

    序列号与签名之间使用一个半角空格;算法值必须小写 md5 / sha256,十六进制签名比较不区分大小写。此处是 HASH(body + key),不是 HMAC。

    所有响应参数均为 JSON 格式。

    按字段类型解析:result_code 与金额等常用标量为字符串;biz_response / data / extended 为对象,集合为数组,错误字段可为空或省略。

    SGD 金额用新加坡分的整数字符串,例如 SGD 1.00 = "100";不用浮点数。接口本身不通过示例金额自动选择币种,需确认商户/渠道币种配置。

    凭证使用范围

    适用范围序列号密钥
    /terminal/activatevendor_snvendor_key
    其他所有接口terminal_snterminal_key

    请求示例

    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"
      }'

    本地签名测试向量

    下例仅验证字节拼接和编码,凭证是虚构值,不可直接调用支付 API;Body 末尾没有换行。完整示例的 selftest 使用同一 SHA256 向量。

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

    下面接口的 cURL 只示意报文形态,<sign> 必须按最终请求体实时计算;推荐先运行完整 Python 示例,避免签名与实际发送的 JSON 不一致。

    回调验签

    回调签名验证

    网关 V2 支付通知使用 SHA256withRSA;取消通知结构另见异步回调章节。请对原始请求体验签,验签通过前不处理业务。

    1. 取整个 Authorization 头作为 RSA 签名;它不带 terminal_sn 前缀。
    2. 读取并保留原始 UTF-8 请求字节;不要先解析再序列化。
    3. 使用对应环境的平台公钥;上线前确认公钥发放与轮换流程。
    4. 使用平台公钥按 SHA256withRSA 验签;通过后再解析 JSON 并核对订单与金额。
    5. 可靠保存合法通知后返回 HTTP 2xx + 纯文本 success;无效签名不更新订单。

    响应签名验证

    正常业务响应使用 V2 签名,验签对象是收到的原始响应字节。认证早期失败可能没有有效签名;这种响应只能用于排障,不能作为可信业务结果。

    响应头:
    Authorization: <terminal_sn> <response_sign>

    普通交易响应用本次请求的算法与成功匹配的 terminal_key;激活响应仍用 vendor_sn / vendor_key。签到成功响应改用返回的新 terminal_key,见签到章节。

    异步回调通知

    支付平台通过 HTTP POST 向商户系统推送支付结果。必须实现回调处理,同时结合其他方式确认结果。

    接口信息

    • 通知方向: 支付平台 → 商户服务器
    • 请求方法: POST Content-Type: application/json
    • 验签方式: RSA SHA256WithRSA;从 Authorization 请求头获取 sign,使用公钥验证

    回调参数(核心字段)

    参数类型说明
    snString(16)系统订单号
    client_snString(32)商户订单号(out_trade_no)
    trade_noString(64)支付渠道订单号(支付成功时提供)
    typeString流水类型:PAYMENT、REFUND、CANCEL 等;与 status 一起判断。
    tsnString平台交易流水号;同一订单可对应多条流水。
    client_tsnString该交易流水的外部标识;退款时用于关联原退款业务。
    statusString(32)交易流水状态
    order_statusString(32)当前订单状态
    total_amountString(10)交易总金额
    net_amountString(10)订单剩余未退原始金额;不是扣手续费后的结算净收入。
    paywayString渠道支付方式编码,例如 PayNow=3001;与推单 pay_type 枚举不同。
    finish_timeString(13)当前流水完成时间(Unix 毫秒);退款通知可能是退款完成时间。
    subjectString(64)交易摘要

    验签流程

    1. 保留原始请求字节,读取整个 Authorization 签名值
    2. 使用环境对应的平台公钥进行 SHA256withRSA 验签
    3. 通过后解析 JSON,核对订单、金额、流水类型和状态
    4. 可靠保存通知,幂等处理或异步处理业务
    5. 返回 HTTP 2xx,Body 为纯文本 success(无引号、无换行)

    回调应答

    success

    HTTP 状态须为 2xx,Body 必须恰好是小写 success,不含引号、空格或换行;验签并可靠保存后再应答。

    重要
    • 按流水类型、tsn 与状态实现业务幂等,并核对商户/订单范围;不能只按 sn 永久去重,否则会漏处理后续退款。
    • 执行业务逻辑前必须验证签名。
    • 回调与主动轮询查询应配合使用,不要仅依赖回调。 遇到冲突时按同一订单及流水重新查询核实;旧通知不得覆盖更新状态,持续不一致进入人工核对。

    通知投递与接收实现

    支付通知示例

    以下为虚构值的最小字段示例;真实通知为直接 JSON 对象,不包裹 biz_response。tsn/type/status 标识当前流水和状态,client_tsn 是该流水的外部标识,退款流水不能当成新的付款。

    {
      "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 编码实现;上线前用目标环境的含中文通知样本验签通过,详见核验范围。

    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/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 及已核实的商户、设备映射关联,不能强制要求通知终端号等于请求方终端号。

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

    使用相同的网关 RSA 验签和纯文本应答规则。按原订单及取消业务去重,并查询核实最终结果;不要要求取消通知一定具有支付流水字段。

    签名汇总

    所有接口调用均采用 V2 签名机制。签名计算方式为 HEX(HASH(request_body_bytes + secret_key)),其中 HASH 支持 MD5 和 SHA256。通过 Authorization-Type 请求头指定算法,默认为 md5。

    接口类型凭证算法(V2)
    /terminal/activatevendor_sn + vendor_keyMD5 或 SHA256(十六进制)
    /terminal/checkinterminal_sn + terminal_key请求用当前密钥;成功响应用返回的新密钥,见签到章节。
    /appPush/tradePushterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
    /mis/refundterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
    /upay/v2/refundterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
    /upay/v2/queryterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
    /mis/shiftterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
    /mis/closeterminal_sn + terminal_keyMD5 或 SHA256(十六进制)
    异步回调通知平台公钥RSA SHA256WithRSA