1. 默认模块
Wayflow
  • 默认模块
    • 接入指南
    • 认证与签名
    • 加密与解密
    • Webhook 通知
    • 错误码与重试
    • 关于SDK
      • SDK 使用指南
      • PHP 快速开始
      • Java 快速开始
      • Node.js / TypeScript 快速开始
      • Python 快速开始
      • Go 快速开始
    • 卡产品组
      • 卡产品组列表（分页）
        POST
      • 卡产品组列表（非分页）
        POST
      • 卡产品组详情
        POST
    • 卡产品
      • 卡产品相关字典
        • 费用模型字典
        • 舍入模式字典
      • 卡产品列表（分页）
        POST
      • 卡产品列表（非分页）
        POST
      • 卡产品详情
        POST
    • 卡钱包
      • 卡钱包划转
        • 卡钱包转出
        • 卡钱包转入
      • 卡钱包相关字典
        • 交易订单状态字典
        • 交易订单流向字典
        • 交易订单审批状态字典
      • 卡钱包查询
        • 卡钱包列表（分页）
        • 卡钱包列表（非分页）
        • 卡钱包详情
    • 卡片交易
      • 交易查询
        • 卡片交易列表（分页）
        • 卡片交易列表（非分页）
        • 卡片交易详情
      • 卡片交易相关字典
        • 交易类型字典
        • 交易状态字典
        • 交易商户国家字典
        • 交易资金流向字典
    • 卡钱包交易
      • 卡钱包交易订单
        • 卡钱包转账订单列表（分页）
        • 卡钱包转账订单列表（非分页）
        • 卡钱包转账订单详情
        • 取消卡钱包转账订单
      • 卡钱包交易流水
        • 卡钱包流水列表（分页）
        • 卡钱包流水列表（非分页）
        • 卡钱包流水详情
    • 卡片
      • 卡片查询
        • 卡片列表（分页）
        • 卡片列表（非分页）
        • 卡片详情
        • 查询卡片敏感信息
      • 卡片发行
        • 发卡预检
        • 发卡
      • 卡片更新
        • 消费控制配置示例
        • 更新卡片消费规则
        • 更新卡片别名
      • 卡片状态操作
        • 卡片冻结
        • 卡片解冻
        • 卡片注销
      • 卡片任务
        • 发卡任务详情
        • 发卡任务明细（分页）
        • 批量修改卡片状态
        • 卡片状态任务明细（分页）
        • 卡片状态任务详情
      • 商户查询
        • 商户列表（分页）
        • 商户详情
      • 卡片相关字典
        • 卡片状态字典
        • 国家字典
        • 消费限制类型字典
        • 消费限额周期字典
        • 时区字典
  1. 默认模块

认证与签名

本页说明 API 请求、响应及 Webhook 的签名规则。使用 SDK 时，签名和验签由 SDK 处理，接入步骤见接入指南。

请求头#

请求头填写方式说明
X-Api-Key初始化配置API Key 调用凭证
X-API-VERSION调用时传入接口版本，必填
X-TimestampSDK 自动生成Unix 毫秒时间戳
X-NonceSDK 自动生成每次请求唯一
X-SignatureSDK 自动生成标准 Base64 签名
X-Signature-AlgorithmSDK 自动携带RSA-SHA256
X-Request-IdSDK 自动生成，可调用时传入请求关联 ID；加密请求还用于 AAD
X-Idempotency-Key调用时传入按具体接口要求填写；同一业务重试复用
X-Platform-Encryption-Key-IdSDK 根据密钥生成加密请求使用的平台加密公钥指纹
Content-TypeSDK 自动携带JSON 请求使用 application/json
敏感响应的加密时间戳从信封 AAD 获取，处理方式见加密与解密。

请求签名#

当前生产规范串为 7 行，UTF-8 编码，以 LF 连接，末尾不加换行；空 query 保留空行：
METHOD
EXTERNAL_PATH
CANONICAL_QUERY
TIMESTAMP
NONCE
API_VERSION
BODY_SHA256_HEX
使用客户端鉴权私钥执行 RSA-SHA256，RSA padding 为 PKCS#1 v1.5，结果编码为标准 Base64。X-Api-Key、X-Signature-Algorithm 和幂等键不在此版本规范串中。
METHOD 使用大写；路径不包含域名或 query，不自行增加内部前缀。
GET、HEAD、DELETE 使用空 body 摘要；其余方法对实际发送的原始字节计算 SHA-256 小写 hex。
JSON 只序列化一次。加密请求对信封 JSON 计算摘要，而不是业务明文。
空 body 摘要为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。

Query 规范化#

当前生产规则：拆分键值对 → percent 解码（+ 按空格解码）→ 按解码后的 key、value 的 UTF-16 码元顺序排序 → 重编码 → 用 & 连接。
重编码保留字母、数字及 -._*，其余使用 UTF-8 percent 编码和大写 hex；空格输出 %20，字面加号输出 %2B，~ 输出 %7E。重复 key 保留，空值保留 =。
原 query规范化结果
b=2&a=1a=1&b=2
a=2&a=10&a=1a=1&a=10&a=2
flagflag=
q=hello+worldq=hello%20world
使用 SDK 的 query 参数构造 URL，不手工重复编码。

响应验签#

先保留原始响应体字节，再验证 X-Response-Signature。当前生产规范串为 5 行，LF 连接，末尾无换行：
REQUEST_ID
HTTP_STATUS
CONTENT_TYPE
RESPONSE_TIMESTAMP
RESPONSE_BODY_SHA256_HEX
字段来源
REQUEST_ID响应 X-Request-Id；缺失时使用本次发送的请求 ID
HTTP_STATUSHTTP 状态码十进制字符串
CONTENT_TYPE响应头原始 Content-Type
RESPONSE_TIMESTAMPX-Response-Timestamp
RESPONSE_BODY_SHA256_HEX原始响应体 SHA-256 小写 hex
使用平台鉴权公钥、RSA-SHA256 / PKCS#1 v1.5 验签。验签失败不得使用业务数据；不要先解析并重新序列化响应体。
SDK 默认验证带签名的响应；成功 HTTP 响应缺少签名时报错。非 2xx 且无签名的网关错误仅作未验签错误处理，不当作可信业务响应。

Webhook 验签#

使用平台鉴权公钥验证 X-SlaunchX-Signature。规范串固定 4 行，LF 连接，末尾无换行：
DELIVERY_ID
EVENT_TYPE
TIMESTAMP
BODY_SHA256_BASE64
前三行分别取自 X-SlaunchX-Delivery-Id、X-SlaunchX-Event-Type、X-SlaunchX-Timestamp；第四行是原始 HTTP body 的 SHA-256 标准 Base64，不是 hex。签名算法仍为 RSA-SHA256 / PKCS#1 v1.5。
验签后按加密与解密核对接收方、AAD 和信封，再按Webhook 通知处理事件。
修改于 2026-09-15 15:47:06
上一页
接入指南
下一页
加密与解密
Built with