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
• Your sandbox or production TokenId

🚧

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, TokenId, Cipher, etc.). Here’s a simplified example for the StartAuthentication endpoint:

   JSON

   {
     "TokenId": 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.

   JSON

   {"TokenId":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

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

   2. Hash the result using SHA-256 (UTF-8 encoded) and 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="
   }'
   

🚧

UTF-8 Encoding

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

See Also