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:

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.