Skip to main content
StartSession
This is the initial API call sent by Nayax. It initiates the transaction session by authenticating both parties and generating a SparkTransactionId, which will be echoed in all subsequent calls throughout the transaction’s lifecycle.

Try it: Spark Auth Tool

Build or inspect the StartSession cipher in your browser, no code required. Opens the tool on the StartSession tab.

How to Build the Cipher

Nayax sends a Random string in the StartSession request. You return an encrypted string called a cipher in your response. The cipher proves that you hold the same Secret Token as Nayax.

Step 1: Create the 64-character Plaintext

Combine these three parts in the exact order and character positions shown below to make one long string: Example: 12c7cec2-c690-4425-9a1f-db0db60e2d8c=123456789qwertyuioasdfghjkl The StartSession cipher has no timestamp. The Random value in the cipher must match the Random value in the Nayax request.

Step 2: Get Your Encryption Key

Nayax provides you with a Secret Token and its Token ID. The request carries the Token ID in TokenId. 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-256 (ECB mode) with PKCS7 padding and your key from Step 2. Then, encode the result into Base64. The result is a 108-character string. Return it in the Cipher field of your StartSession response, together with the SparkTransactionId. This cipher is not the StartAuthentication cipher. The two ciphers use different plaintexts, so you can’t use one in place of the other. Nayax decrypts the cipher with the same key and checks the Random value and the cipher format.
Use the Spark Transaction ID in later calls: Nayax and you send the same SparkTransactionId in all later API calls of this transaction. When a call from Nayax arrives, check that its SparkTransactionId is one that you generated.

Body

application/json

The payload to initiate a new session.

The request payload sent by the Spark platform to the integrator's configured StartSession endpoint to initiate a transaction session.

HwSerial
string

The serial number of the payment terminal hardware.

MachineId
integer<int64>

The unique identifier for the Nayax machine.

TokenId
integer<int32>

A unique token provided by Nayax for secure authentication.

Random
string

A 27-character random alphanumeric string that Nayax creates for this session. Put it after the = in the cipher plaintext.

Response

200 - application/json
object | null

Success. A new session has been successfully initiated.

The response payload from the StartSession endpoint, containing encrypted data and the session status.

Cipher
string

The Base64 result of encrypting SparkTransactionId=Random with AES-256 in ECB mode and PKCS7 padding, using the 32 rightmost characters of the Secret Token as the key. The result is 108 characters.

SparkTransactionId
string | null

A unique GUID with hyphens (36 characters) that you generate for this transaction. Nayax and you send it in all later calls of the transaction.

Status
object

Transaction Status Details