加签说明

接入凭证

商户调用 OpenAPI 前需要获取一组启用状态的 OpenAPI 凭证：

项	说明
apiKey	商户 Ed25519 公钥 raw bytes hex，同时作为请求头 X-Api-Key。
merchantPrivateKey	商户自己保存的 Ed25519 私钥，用于生成 X-Signature。FuturePay 不保存该私钥。
futurePayPublicKey	FuturePay 平台 Ed25519 公钥 raw bytes hex，用于商户验 FuturePay 响应签名。

请求签名 Header

正式环境下，除 FuturePay 明确约定免签的运维路径外，OpenAPI 请求均应携带以下 Header：

Header	类型	必填	说明
X-Api-Key	string	是	商户 Ed25519 公钥 hex。支持 64 位 raw public key hex，代码兼容部分 88 位格式。
X-Timestamp	string	是	毫秒级 Unix 时间戳，例如 1784611200000。默认允许服务端当前时间前后 300 秒。
X-Nonce	string	是	随机字符串，同一租户、同一环境、同一时间窗口内不可重复。
X-Signature	string	是	Ed25519 签名结果，小写或大写 hex 均可，长度 128 位。

请求签名串

请求签名原文固定为：

METHOD|PATH|TIMESTAMP|NONCE|QUERY_STRING|RAW_BODY

片段	说明
METHOD	HTTP 方法大写，例如 GET、POST。
PATH	实际请求路径，不包含域名和 query string。签名时必须使用服务端收到的路径。
TIMESTAMP	与 X-Timestamp 完全一致。
NONCE	与 X-Nonce 完全一致。
QUERY_STRING	原始 query string，不包含 ?。没有 query 时为空字符串。
RAW_BODY	原始请求体字符串。multipart/form-data 上传接口按空字符串参与签名。

路径说明：本文接口路径以 /openapi/v1/** 展示。如果直接访问 future-app 服务且部署保留应用上下文 /openapi/，完整请求路径可能是 /openapi/openapi/v1/**。签名中的 PATH 必须以实际 HTTP 请求路径为准。

签名步骤

1. 生成毫秒级时间戳 timestamp。
2. 生成随机 nonce。
3. 准备原始请求体 rawBody。JSON 请求必须使用实际发送的 JSON 字符串；GET 请求和 multipart 上传请求使用空字符串。
4. 按 METHOD|PATH|TIMESTAMP|NONCE|QUERY_STRING|RAW_BODY 拼接签名串。
5. 对签名串做一次 SHA-256，得到 32 字节摘要。
6. 使用商户 Ed25519 私钥对摘要签名。
7. 将签名结果转为 hex，放入 X-Signature。

示例签名串：

POST|/openapi/v1/cards/recharge|1784611200000|nonce-001||{"requestNo":"REQ001","cardId":"CARD001","amount":10,"currency":"USDT"}

响应签名

FuturePay 在已完成 OpenAPI 鉴权的响应中写入平台签名 Header：

Header	类型	说明
X-FP-Api-Key	string	FuturePay 平台 Ed25519 公钥 hex。
X-FP-Timestamp	string	FuturePay 生成响应签名时的毫秒级时间戳。
X-FP-Signature	string	FuturePay 平台响应签名 hex。
X-FP-Body-Hash	string	响应 body 的 SHA-256 hex。

商户验响应签名时，签名原文为：

X-FP-Timestamp|RAW_RESPONSE_BODY

验签步骤：对上述原文做 SHA-256，再使用 X-FP-Api-Key 对应的 FuturePay 公钥验 X-FP-Signature。

鉴权失败响应

鉴权失败时 HTTP 状态码可能为 401 或 403，响应体仍使用统一结构：

{
  "code": 401,
  "msg": "SIGNATURE_INVALID: 签名校验失败",
  "data": null
}

常见错误码：

错误码	HTTP 状态	说明
API_KEY_MISSING	401	未传 X-Api-Key。
API_KEY_INVALID	401	API Key 不存在、格式错误或环境不匹配。
REQUEST_HEADER_MISSING	401	缺少 X-Timestamp、X-Nonce 或 X-Signature。
CREDENTIAL_DISABLED	403	凭证未启用、已禁用或已过期。
IP_NOT_ALLOWED	403	请求来源 IP 不在白名单。
SIGN_TIMESTAMP_EXPIRED	401	时间戳超出允许窗口或格式错误。
SIGNATURE_INVALID	401	签名校验失败。
NONCE_REPLAYED	401	nonce 已在时间窗口内使用。