> ## 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. # StartAuthentication The `StartAuthentication` endpoint is the first step for any External Settlement. Use this to verify your server’s identity with Nayax and create a secure link for the transaction. > [card] [Try it: Spark Auth Tool](https://devzone.nayax.com/docs/integrate-pos-device/spark/security-authentication/spark-auth-tool.md) > > Build and inspect the cipher and the `TransactionSignature` header for this endpoint in your browser, no code required. ## How to Build the Cipher You must send an encrypted string called a `cipher`. This string tells Nayax which transaction you are working on and proves the request is current. ### Step 1: Create the 64-character Plaintext Combine these four parts in the exact order and character positions shown below to make one long string: | Section | Type | Position | Description | | - | - | - | - | | **Spark Transaction ID** | String | 1-36 | Your unique GUID (with hyphens). | | **Separator** | Special | 37 | Must be the `=` symbol. | | **Random String** | String | 38-54 | A 17-character random alphanumeric string. | | **Timestamp** | Numeric | 55-64 | Current UTC time in `YYMMDDhhmm` format. | **Example:** `12c7cec2-c690-4425-9a1f-db0db60e2d8c=123456789qwertyui2602041044` ### Step 2: Get Your Encryption Key Nayax provides you with a **Secret Token** (usually 66 characters). To create your key, take only the **32 characters on the far right** of that token to create a 256-bit key. **Example:** * **Full token example:** `...wRvTVTkungMIKThTVbj_fiXdfoGclhn0` * **What your key will look like:** `wRvTVTkungMIKThTVbj_fiXdfoGclhn0` ### Step 3: Encrypt and Encode Encrypt the 64-character string from Step 1 using **AES (ECB mode)** with your key from Step 2. Then, encode the result into **Base64**. > [!NOTE] > > **Important Rules for Success:** > > * **5-Minute Window**: Nayax will reject any request if the timestamp in your cipher is more than 5 minutes old. This limit is controlled by the `CipherExpMinutes` variable. > * **Double-Check Randomness**: The `Random` field in your JSON request must be exactly the same as the random string you put inside the cipher. > * **Verify Nayax**: When the response arrives, it contains a `HashedSparkTransactionId`. You **must** hash your original Transaction ID using **SHA-256** and ensure it matches Nayax’s version to verify the response is authentic. ### Error Codes If your request is declined, look for these specific codes: | Error Code | Meaning | What to Check | | - | - | - | | **28** | Invalid Token | Check if your Token ID is correct, active, and associated with your account. | | **30** | Validation Failed | Your JSON `Random` field doesn't match the one in your cipher. | | **31** | Expired Request | Your timestamp is too old (longer than 5 minutes). Sync your server clock to UTC. | | **34** | Decryption Failure | Your cipher format is wrong or the `=` is missing from the 37th character. | ## OpenAPI ````yaml /openapi/zh/spark.yaml post /StartAuthentication openapi: 3.0.1 info: title: Nayax Spark API description: RemoteStart V2 version: v2 servers: - url: https://nayax-spark-dmz.nayax.com/api description: The same host serves the integration and production environments. security: [] tags: - name: Transactions paths: /StartAuthentication: post: tags: - Transactions summary: StartAuthentication requestBody: description: The request payload for transaction authentication. required: true content: application/json: schema: $ref: '#/components/schemas/StartAuthenticationRequest' responses: '200': description: Success. The transaction request was successfully authenticated. content: application/json: schema: $ref: '#/components/schemas/StartAuthenticationResponse' components: schemas: StartAuthenticationRequest: type: object nullable: true description: > The request payload for the `/spark/StartAuthentication` endpoint. This call is the initial step for a transaction, authenticating the request and preparing the session. properties: TokenId: type: integer format: int32 description: | A unique token provided by Nayax to identify your integration. TerminalId: type: string nullable: false description: | The unique device ID of the target terminal. TerminalIdType: type: integer format: int32 description: > Defines the type of `TerminalId` being used. Use `1` for the hardware serial number (`HW Serial`) or `2` for the Nayax Machine ID. Random: type: string nullable: false description: | A random string used as part of the encryption handshake. Cipher: type: string nullable: false description: > The AES-256 ECB encrypted payload. This is a Base64-encoded string that contains the Spark Transaction ID, a random string, and a timestamp. example: TokenId: 116383 TerminalId: '0434334921100366' TerminalIdType: 1 Random: 123456789qwertyui Cipher: >- X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw= StartAuthenticationResponse: type: object nullable: true description: > The response payload from the `/spark/StartAuthentication` endpoint. It provides a unique hashed transaction ID and the authentication status. properties: HashedSparkTransactionId: type: string nullable: false description: > A SHA256 hash of the `SparkTransactionId` sent in the request. This ID must be used for all subsequent steps of the transaction. Status: $ref: '#/components/schemas/Status' example: HashedSparkTransactionId: 9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7 Status: Verdict: Approved ErrorDescription: ' No Errors ' Status: type: object nullable: false description: 交易状态详情 properties: Verdict: type: string nullable: false description: 请求的状态（Approved / Declined） ErrorCode: type: integer format: int16 nullable: true description: | - 条件必填 - 请求被拒绝的原因 ErrorDescription: type: string nullable: true description: | - 条件必填 - 长度：255 - 错误描述 StatusMessage: type: string nullable: true description: | - 可选 - 长度：255 - 交易状态消息，自由文本字段 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.