加签说明

接入凭证

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

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

商户可使用 OpenSSL 生成 apiKey 和 merchantPrivateKey：

openssl genpkey -algorithm ed25519 -out private_key.pem

openssl pkey -in private_key.pem -pubout -out public_key.pem

echo "Private Key (Hex )/merchantPrivateKey:"
openssl pkey -in private_key.pem -text | grep 'priv:' -A 3 | tail -n +2 | tr -d ':\n ' && echo

echo "Public Key (Hex)/apiKey:"
openssl pkey -pubin -in public_key.pem -text | grep 'pub:' -A 3 | tail -n +2 | tr -d ':\n ' && echo

商户需自行妥善管理 merchantPrivateKey。在 FuturePay 商户管理后台中的“Api 凭证”页面上新增 apiKey 后，系统会返回 futurePayPublicKey / FPAPIKey。

请求签名 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/cards/recharge。签名中的 PATH 必须与实际请求 URL 的 path 完全一致，不包含域名和 query string；请勿额外重复拼接 /openapi。

签名步骤

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。

商户 webhook 回调

FuturePay 向商户配置的回调地址发送 JSON webhook 时，也会携带上述四个 X-FP-* Header。签名原文为：

X-FP-Timestamp|RAW_CALLBACK_BODY

商户必须使用收到的原始请求体完成验签，不能先解析 JSON 后重新序列化。HTTP 2xx 表示接收成功；超时、网络异常或非 2xx 可能触发重复投递。

每个回调 Payload 都包含稳定的 eventNo。FuturePay 采用至少一次投递语义，自动重试和人工重放保持相同的 eventNo 与请求体；商户应以 eventNo 做幂等处理。

完整的后台配置、事件类型、重试规则和接入检查见 商户 Webhook。

鉴权失败响应

鉴权失败时 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 已在时间窗口内使用。