Security & Authentication

Spark uses a two-part security mechanism:

• Token-based identification to associate the request with your account.
• HMAC signature using a shared secret (Sign Key) to ensure the request body hasn’t been tampered with in transit.

This page will guide you to securely authenticate Spark API requests using Nayax’s custom HMAC signature mechanism. This involves signing each request body with a shared Sign Key and attaching two mandatory headers: Signature and IntegratorId.

Pre-requisites

Before you begin, make sure you have the following resources:

• A valid Sign Key (shared by Nayax, typically 16 characters)
• The associated Sign Key ID

🚧

Mandatory

This signature mechanism is required for all Spark endpoints. Requests without a valid signature will be rejected with 401 Unauthorized.

Authenticate Requests

Once you have the required resources, you can start authenticating your API requests to Spark by following the steps below:

1. Prepare the JSON body with all the necessary fields (e.g., TerminalId, Cipher, etc.). Here’s a simplified example for the StartAuthentication endpoint:

   JSON

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

2. Serialize the JSON request content, removing whitespace and line breaks. Do not alter values or add escape characters unless they are part of the actual payload.

   

   We used this JSON lint tool to do so in the example. The result is the following.

   JSON

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

3. Generate the Signature header following the steps below:

   1. Concatenate the serialized request and the Sign Key, separated by ";".

      JSON

      {"TokenlId":116383,...,"Cipher":"..."};RbtdDsiVNjkAeRty

   2. Hash the result using SHA-256 (UTF-8 encoded):

      

      We used this tool to do so in the example. Use the output as your Signature header.

      JSON

      536a5813206bcb663d98715d10a6b2612364245c865cdd5f781ff4428c4a6137

4. Add the IntegratorId and Signature headers to your request.

   JSON

   curl -X POST https://api-sandbox.nayax.com/spark/StartAuthentication \
   --header 'IntegratorId: 927' \
   --header 'Signature: 536a5813206bcb663d98715d10a6b2612364245c865cdd5f781ff4428c4a6137' \
   --header 'Content-Type: application/json' \
   --data '{
     "TokenId": 116383,	
     "TerminalId": "0434334921100366",
     "TerminalIdType": 1,
     "Random": "123456789qwertyui",
     "Cipher": "X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw="
   }'

For this example, the /StartAuthentication method was used, but the process is relevant for any Spark endpoint request and response.

🚧

UTF-8 Encoding

Ensure the Signature is correctly generated from the minified JSON and UTF-8 hash.

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=

See Also