Skip to main content
POST
/
validate-merchant
Validate Merchant (Start Authentication)
curl --request POST \
  --url https://api.nayax.com/sdk/validate-merchant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokenId": 116383,
  "actorId": "someActorId",
  "machineId": "0434334921100366",
  "random": "123456789qwertyui",
  "cipher": "X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trBuNJwBEjgBzKhhgpJ5ggnw="
}
'
{
  "verdict": "Approved",
  "code": 0,
  "statusMessage": "Merchant authenticated successfully.",
  "customDeclineCode": "9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7"
}
An initial call by Nayax to the Integrator to securely authenticate both Nayax and the 3rd party regarding a possible transaction. During this process, the integrator generates a Transaction ID (“Ecom Transaction ID”) to be echoed in following calls. Security Flow:
  1. Nayax and the integrator pre-share a Secret Token (e.g., mrV3U3nsgGFrE3w5-wnBo_WCLPce-pZ1awRvTVTkungMIKThTVbj_fiXdfoGclhn0 with Token ID: 116383).
  2. Nayax creates a 27-character Random String and sends it to the Integrator in the StartAuthentication request (e.g., 123456789qwertyuiopasdfghjk).
  3. The Integrator generates a 64-character Ciphertext with the structure Ecom Transaction ID||=||Random String (e.g., 12c7cec2-c690-4425-9a1f-db0db60e2d8c=123456789qwertyuiopasdfghjk).
  4. The Integrator produces an encryption key from the 32 rightmost characters of the Token (e.g., wRvTVTkungMIKThTVbj_fiXdfoGclhn0).
  5. The Integrator encrypts the Ciphertext using AES in ECB mode and sends the produced cipher in the /validate-merchant (StartAuthentication) Request.
  6. Nayax decrypts the Cipher using the same key and performs validations on the Random and Cipher Format.
  7. Nayax and the Integrator should send the Ecom Transaction ID (12c7cec2-c690-4425-9a1f-db0db60e2d8c) in all future API calls of the same transaction.
  8. The Integrator shall validate that the Ecom Transaction ID sent from Nayax was generated by them in further API calls.
See Security & Authentication for more details.
Integration URLWhen performing your integration to the API use the stable URL, such as:
  • https://stable-sdk-api.nayax.com/validate-merchant

Authorizations

​
Authorization
string
header
required

JWT RSA token required for authentication. The token should be included in the Authorization header as Bearer <token>. Nayax will issue tokens to the VAS, signed by a private key, and decrypt them using a public key.

Body

application/json

Request to validate the merchant and initiate authentication.

Request body for validating a merchant and initiating authentication.

​
tokenId
integer<int32> | null

Token ID provided by Nayax to the VAS.

Example:

116383

​
actorId
string | null

The unique identifier for the actor/integrator.

Example:

"someActorId"

​
machineId
string | null

Machine ID allocated in the Nayax Backoffice.

Example:

"0434334921100366"

​
random
string | null

A 27-character random string generated by Nayax and sent to the Integrator.

Example:

"123456789qwertyui"

​
cipher
string | null

A 64-character long ciphertext generated by the Integrator by encrypting the Ecom Transaction ID||=||Random String using AES in ECB mode with an encryption key derived from the Secret Token.

Example:

"X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trBuNJwBEjgBzKhhgpJ5ggnw="

Response

Success

General status object for API responses.

​
verdict
string | null
required

Const string values 'Approved' or 'Declined'.

Example:

"Approved"

​
code
integer<int32>

Response code. 0 for Approved, relevant decline code for Declined.

Example:

0

​
statusMessage
string | null

Optional. Session status message free text field or additional varying data.

Maximum string length: 255
Example:

"Transaction processed successfully."

​
customDeclineCode
string | null

Custom decline code, can also be used to return the HashedEcomTransactionId for validate-merchant success.

Example:

"9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7"