Guides

StartAuthentication

Suggest Edits

The StartAuthentication endpoint is the first step in any Spark transaction. It authenticates the transaction request using a pre-shared token and a cryptographically signed payload.

Spark responds with a unique HashedSparkTransactionId that must be used in all subsequent steps.

Request

The integrator sends a POST request to the /spark/StartAuthentication endpoint. The body parameters need to be as in the example below:

{
 "TokenId": 116383,
 "TerminalId": "0434334921100366",
 "TerminalIdType": 1,
 "Random": "123456789qwertyui",
 "Cipher": "X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/tr
zBuNJwBEjgBzKhhgpJ5ggnw="
}

🚧

Security

This request must be signed with the Signature and IntegratorId headers. See Security & Authentication to learn more.

Request Parameters

The table below describes the parameters of the request:

FieldTypeRequiredDescription
TokenIdIntegerYesA unique token provided by Nayax to identify your integration
TerminalIdStringYesThe target terminal's unique device ID
TerminalIdTypeIntegerYesDefines the ID type used. 1 for HW Serial, 2 for Nayax Machine ID.
RandomStringYesRandom string used as part of the encryption handshake
CipherStringYesAES-256 ECB encrypted payload using Token. See the section below to learn how to build this cipher.

Build Cipher

Your ciphertext combines the following:

  • A 36-character Spark Transaction ID (a GUID with hyphens).
  • A single "=" character.
  • A 17-character alphanumeric Random String.
  • A 10-character YYMMDDhhmm UTC Timestamp.

Follow these steps to generate and encrypt your cipher:

  1. Concatenate the Spark Transaction ID, the "=" character, the Random String, and the Timestamp to form the 64-character ciphertext, as in the example below: 
    12c7cec2-c690-4425-9a1f db0db60e2d8c=123456789qwertyui2306061021
  2. Extract the 32 rightmost characters from your provided Token to create the 256-bit AES encryption key. For example, suppose the token is the following: 
    some_long_token_wRvTVTkungMIKThTVbj_fiXdfoGclhn0
    The encryption key is as follows: 
    wRvTVTkungMIKThTVbj_fiXdfoGclhn0
  3. Encrypt the 64-character ciphertext using AES in ECB mode. Ensure the plaintext is padded (e.g., using PKCS7) to a multiple of 16 bytes. Base64 encode the resulting encrypted bytes for transmission, which yields an output similar to the example below: 
    X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw=

Response

A successful response will return the following body:

{
 "HashedSparkTransactionId": "9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7",
 "Status": {
   "Verdict": "Approved",
   "ErrorDescription": " No Errors "
 }
}

Response Parameters

The table below describes the parameters of the response:

Parameter NameTypeDescription
HashedSparkTransactionIdStringA SHA256 hash of the Spark Transaction ID sent in the request.
StatusObjectAn object containing details about the transaction's outcome, including its verdict and any associated error descriptions or codes.
Status.VerdictStringIndicates the overall outcome of the authentication attempt. Can be Approved for success or Declined for failure.
Status.ErrorDescriptionStringProvides a human-readable description of any errors that occurred, or indicates No Errors for successful requests.
Status.ErrorCodeNumberA numeric code indicating a specific type of error that occurred during the transaction. This field is present only in error responses.

Updated 9 days ago