> ## Documentation Index
> Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 传统身份验证

Spark 使用两部分安全机制：

* 基于令牌的识别将请求与您的帐户关联起来。
* 使用共享密钥（`Sign Key`）的 HMAC 签名，以确保请求正文在传输过程中未被篡改。

本页面将指导您使用 Nayax 的自定义 HMAC 签名机制安全地对 Spark API 请求进行身份验证。这包括使用共享的 `Sign Key` 对每个请求正文进行签名，并附加两个必需的请求头：`Signature` 和 `IntegratorId`。

## 先决条件

开始之前，请确保您拥有以下资源：

* 有效的签名密钥（由 Nayax 共享，通常为 16 个字符）
* 关联的签名密钥 ID

> [!WARNING]
>
> 强制的
>
> 所有 Spark 端点都要求使用此签名机制。没有有效签名的请求将被拒绝，并返回 `401 Unauthorized`。

## 验证请求

拥有所需的资源后，您可以按照以下步骤开始向 Spark 验证您的 API 请求：

1. 准备包含所有必要字段（例如 `TerminalId`、`Cipher` 等）的 JSON 正文。以下是 [StartAuthentication](https://devzone.nayax.com/reference/spark/transactions/startauthentication.md) 端点的简化示例：

   ```json theme={null}
   {
     "TokenId": 116383,  
     "TerminalId": "0434334921100366",
     "TerminalIdType": 1,
     "Random": "123456789qwertyui",
     "Cipher": "X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw="
   }

   ```
2. 序列化 JSON 请求内容，删除空格和换行符。请勿更改值或添加转义符，除非它们是实际负载的一部分。

   ![](https://mintcdn.com/nayax-44d6e37b/gp-udlFbAMEECcYg/images/docs/spark-legacy-authentication/image1.png?fit=max\&auto=format\&n=gp-udlFbAMEECcYg\&q=85\&s=fe21e4e1e5ffdbbde556d7c3ddaa47e0)

   我们在示例中使用了这款[JSON 代码检查工具](https://jsonlint.com/)。结果如下。

   ```json theme={null}
   {"TokenId":116383,"TerminalId":"0434334921100366","TerminalIdType":1,"Random":"123456789qwertyui","Cipher":"X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw="}
   ```
3. 请按照以下步骤生成 `Signature` 头：
   1. 将序列化的请求和签名密钥连接起来，用“;”分隔。
      ```json theme={null}
      {"TokenId":116383,...,"Cipher":"..."};RbtdDsiVNjkAeRty
      ```
   2. 使用 SHA-256 算法（UTF-8 编码）对结果进行哈希处理：

      ![](https://mintcdn.com/nayax-44d6e37b/gp-udlFbAMEECcYg/images/docs/spark-legacy-authentication/image2.png?fit=max\&auto=format\&n=gp-udlFbAMEECcYg\&q=85\&s=cdcaaae547a2f8c2e359bd178ee47e01)

      We used [this tool](https://emn178.github.io/online-tools/sha256.html) to do so in the example. Use the output as your `Signature` header.

      ```json theme={null}
      536a5813206bcb663d98715d10a6b2612364245c865cdd5f781ff4428c4a6137
      ```
4. 将 `IntegratorId` 和 `Signature` 头添加到您的请求中。

   > [!NOTE]
   >
   > 基本 URL
   >
   > Spark API 的基础 URL 为 `https://nayax-spark-dmz.nayax.com/api`。集成环境和生产环境使用同一个主机。

   ```json theme={null}
   curl -X POST https://nayax-spark-dmz.nayax.com/api/StartAuthentication \
   --header 'IntegratorId: 927' \
   --header 'Signature: 536a5813206bcb663d98715d10a6b2612364245c865cdd5f781ff4428c4a6137' \
   --header 'Content-Type: application/json' \
   --data '{
     "TokenId": 116383,	
     "TerminalId": "0434334921100366",
     "TerminalIdType": 1,
     "Random": "123456789qwertyui",
     "Cipher": "X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw="
   }'
   ```

For this example, the [`/StartAuthentication`](https://devzone.nayax.com/reference/spark/transactions/startauthentication) method was used, but the process is relevant for any Spark endpoint request and response.

> [!WARNING]
>
> UTF-8 编码
>
> 确保签名是从最小化的 JSON 和 UTF-8 哈希正确生成的。

### 构建 `cipher`

您的密文由以下部分组成：

* 一个 36 个字符的 Spark 事务 ID（一个带有连字符的 GUID）。
* 单个 "=" 字符。
* 一个 17 个字符的字母数字随机字符串。
* 一个 10 个字符的 `YYMMDDhhmm` 格式 UTC 时间戳。

请按照以下步骤生成并加密您的密文：

1. 将 Spark 事务 ID、“=”字符、随机字符串和时间戳连接起来，形成 64 个字符的密文，如下例所示：
   ```
   12c7cec2-c690-4425-9a1f-db0db60e2d8c=123456789qwertyui2306061021
   ```
2. 从提供的令牌中提取最右侧的 32 个字符，以创建 256 位 AES 加密密钥。例如，假设令牌如下：
   ```
   some_long_token_wRvTVTkungMIKThTVbj_fiXdfoGclhn0
   ```
   加密密钥如下：
   ```
   wRvTVTkungMIKThTVbj_fiXdfoGclhn0
   ```
3. 使用 ECB 模式的 AES 加密 64 个字符的密文。确保明文已填充（例如，使用 PKCS7）至 16 字节的倍数。对生成的加密字节进行 Base64 编码以进行传输，这将产生类似于以下示例的输出：
   ```
   X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw=
   ```

## 参见

> **[交互式身份验证工具](https://devzone.nayax.com/docs/integrate-pos-device/spark/security-authentication/spark-auth-tool.md?auth=legacy)**
>
> 在浏览器中构建和检查旧版密文与 `Signature` 请求头，无需编写代码。

> **[交易流程](https://devzone.nayax.com/docs/integrate-pos-device/spark/payment-flows/transaction-flows-spark)**
>
> 身份验证如何融入完整的 Spark 交易流程。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.