签名与通知
请求规范与签名
请求域名
新加坡接入域名由飞书接口文档确认。测试环境地址、凭证与真实扣款边界须在联调开通时单独获取,不能把此域名默认当作沙箱。
请求规范
签名方法
平台接口仅支持 JSON 格式请求。请在 HTTP 请求头中设置 Content-Type: application/json。
所有请求体必须使用 UTF-8 编码,响应也使用相同编码。
调用所有平台接口均需要签名验证。
签名覆盖实际发送的 UTF-8 原始字节。先生成最终 JSON,再签名;字段顺序、空格、转义或末尾换行变化均需重新计算。
Authorization 使用调用方序列号与签名;交易接口中该序列号必须与 Body 的 terminal_sn 一致。
签名算法(V2):
待签名内容为 HTTP 请求体原始字节与密钥直接拼接:激活用 vendor_key,其余本页业务接口用 terminal_key。
其中 HASH 支持 MD5 和 SHA256:
- 默认使用
MD5 - 也可使用
SHA256,增强安全性 - 通过
Authorization-Type请求头指定算法(md5 或 sha256) - 省略
Authorization-Type时,默认使用 md5
签名请求头格式:
序列号与签名之间使用一个半角空格;算法值必须小写 md5 / sha256,十六进制签名比较不区分大小写。此处是 HASH(body + key),不是 HMAC。
所有响应参数均为 JSON 格式。
按字段类型解析:result_code 与金额等常用标量为字符串;biz_response / data / extended 为对象,集合为数组,错误字段可为空或省略。
SGD 金额用新加坡分的整数字符串,例如 SGD 1.00 = "100";不用浮点数。接口本身不通过示例金额自动选择币种,需确认商户/渠道币种配置。
凭证使用范围
请求示例
本地签名测试向量
下例仅验证字节拼接和编码,凭证是虚构值,不可直接调用支付 API;Body 末尾没有换行。完整示例的 selftest 使用同一 SHA256 向量。
下面接口的 cURL 只示意报文形态,<sign> 必须按最终请求体实时计算;推荐先运行完整 Python 示例,避免签名与实际发送的 JSON 不一致。
回调验签
回调签名验证
网关 V2 支付通知使用 SHA256withRSA;取消通知结构另见异步回调章节。请对原始请求体验签,验签通过前不处理业务。
- 取整个
Authorization头作为 RSA 签名;它不带terminal_sn前缀。 - 读取并保留原始 UTF-8 请求字节;不要先解析再序列化。
- 使用对应环境的平台公钥;上线前确认公钥发放与轮换流程。
- 使用平台公钥按 SHA256withRSA 验签;通过后再解析 JSON 并核对订单与金额。
- 可靠保存合法通知后返回 HTTP 2xx + 纯文本
success;无效签名不更新订单。
响应签名验证
正常业务响应使用 V2 签名,验签对象是收到的原始响应字节。认证早期失败可能没有有效签名;这种响应只能用于排障,不能作为可信业务结果。
普通交易响应用本次请求的算法与成功匹配的 terminal_key;激活响应仍用 vendor_sn / vendor_key。签到成功响应改用返回的新 terminal_key,见签到章节。
异步回调通知
支付平台通过 HTTP POST 向商户系统推送支付结果。必须实现回调处理,同时结合其他方式确认结果。
接口信息
- 通知方向: 支付平台 → 商户服务器
- 请求方法: POST Content-Type: application/json
- 验签方式: RSA SHA256WithRSA;从 Authorization 请求头获取 sign,使用公钥验证
回调参数(核心字段)
验签流程
- 保留原始请求字节,读取整个
Authorization签名值 - 使用环境对应的平台公钥进行 SHA256withRSA 验签
- 通过后解析 JSON,核对订单、金额、流水类型和状态
- 可靠保存通知,幂等处理或异步处理业务
- 返回 HTTP 2xx,Body 为纯文本
success(无引号、无换行)
回调应答
HTTP 状态须为 2xx,Body 必须恰好是小写 success,不含引号、空格或换行;验签并可靠保存后再应答。
- 按流水类型、tsn 与状态实现业务幂等,并核对商户/订单范围;不能只按 sn 永久去重,否则会漏处理后续退款。
- 执行业务逻辑前必须验证签名。
- 回调与主动轮询查询应配合使用,不要仅依赖回调。 遇到冲突时按同一订单及流水重新查询核实;旧通知不得覆盖更新状态,持续不一致进入人工核对。
通知投递与接收实现
支付通知示例
以下为虚构值的最小字段示例;真实通知为直接 JSON 对象,不包裹 biz_response。tsn/type/status 标识当前流水和状态,client_tsn 是该流水的外部标识,退款流水不能当成新的付款。
Node.js 验签函数
使用 Node.js 标准库;rawBody 必须是尚未经过 JSON 中间件改写的原始 Buffer。此函数按本地 SDK 的 Base64 编码实现;上线前用目标环境的含中文通知样本验签通过,详见核验范围。
投递规则与应答
本地网关实现首次立即投递;失败后依次等待 1、5、30、600 秒 ,最多重试四次(含首次最多五次)。非 2xx、网络失败、空 Body、带引号或换行的 success 都会导致重试。不要依赖永久重试;持续漏通知由查单和对账补偿。先验签并可靠保存,再快速应答,耗时业务异步处理;没有确认统一的接收超时 SLA。
取消通知是不同的载荷
已核对的预撤单路径(订单尚未生成且允许预撤单)可能向 cancel_notify_url 发送以下结构;它没有支付通知的 sn/type/order_status,不能据此认定顾客已退款。取消通知覆盖范围依设备/路由而异,必须联调;/mis/close 可显式传入取消通知地址。
在已核对的通联/KPay 预撤单路径中,代理将请求中的 terminal_sn 转为目标支付终端号,网关将此值写入取消通知。同商户双终端示例:调用方为 2101107140290972547,目标支付终端为 2101107140290972548;下例返回后者。验签后按 out_trade_no 及已核实的商户、设备映射关联,不能强制要求通知终端号等于请求方终端号。
使用相同的网关 RSA 验签和纯文本应答规则。按原订单及取消业务去重,并查询核实最终结果;不要要求取消通知一定具有支付流水字段。
签名汇总
所有接口调用均采用 V2 签名机制。签名计算方式为 HEX(HASH(request_body_bytes + secret_key)),其中 HASH 支持 MD5 和 SHA256。通过 Authorization-Type 请求头指定算法,默认为 md5。
