> ## 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.
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**.
**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/spark.yaml post /StartAuthentication
openapi: 3.0.1
info:
title: Nayax Spark API
description: RemoteStart V2
version: v2
servers:
- url: https://{domain}/api
variables:
domain:
default: nayax-spark-dmz.nayax.com
description: >-
Your Nayax-assigned domain (e.g., nayax-spark-dmz.nayax.com). Nayax
provides a QA domain during sandbox onboarding and a production domain
after certification.
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: Transaction Status Details
properties:
Verdict:
type: string
nullable: false
description: Status of the request (Approved / Declined)
ErrorCode:
type: integer
format: int16
nullable: true
description: |
- Conditional
- Reason for declined request
ErrorDescription:
type: string
nullable: true
description: |
- Conditional
- Length: 255
- Error description
StatusMessage:
type: string
nullable: true
description: |
- Optional
- Length: 255
- Transaction status message as free text field
````