Skip to main content
StartAuthentication
curl --request POST \
  --url https://{domain}/api/StartAuthentication \
  --header 'Content-Type: application/json' \
  --data '
{
  "TokenId": 116383,
  "TerminalId": "0434334921100366",
  "TerminalIdType": 1,
  "Random": "123456789qwertyui",
  "Cipher": "X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw="
}
'
{
  "HashedSparkTransactionId": "9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7",
  "Status": {
    "Verdict": "Approved",
    "ErrorDescription": " No Errors "
  }
}
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.

​
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:
SectionTypePositionDescription
Spark Transaction IDString1-36Your unique GUID (with hyphens).
SeparatorSpecial37Must be the = symbol.
Random StringString38-54A 17-character random alphanumeric string.
TimestampNumeric55-64Current 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 CodeMeaningWhat to Check
28Invalid TokenCheck if your Token ID is correct, active, and associated with your account.
30Validation FailedYour JSON Random field doesn’t match the one in your cipher.
31Expired RequestYour timestamp is too old (longer than 5 minutes). Sync your server clock to UTC.
34Decryption FailureYour cipher format is wrong or the = is missing from the 37th character.

Body

application/json

The request payload for transaction authentication.

The request payload for the /spark/StartAuthentication endpoint. This call is the initial step for a transaction, authenticating the request and preparing the session.

​
TokenId
integer<int32>

A unique token provided by Nayax to identify your integration.

​
TerminalId
string

The unique device ID of the target terminal.

​
TerminalIdType
integer<int32>

Defines the type of TerminalId being used. Use 1 for the hardware serial number (HW Serial) or 2 for the Nayax Machine ID.

​
Random
string

A random string used as part of the encryption handshake.

​
Cipher
string

The AES-256 ECB encrypted payload. This is a Base64-encoded string that contains the Spark Transaction ID, a random string, and a timestamp.

Response

200 - application/json
object | null

Success. The transaction request was successfully authenticated.

The response payload from the /spark/StartAuthentication endpoint. It provides a unique hashed transaction ID and the authentication status.

​
HashedSparkTransactionId
string

A SHA256 hash of the SparkTransactionId sent in the request. This ID must be used for all subsequent steps of the transaction.

​
Status
object

Transaction Status Details