> ## Documentation Index
> Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate Merchant (Start Authentication)



## OpenAPI

````yaml openapi/ecom.yaml POST /validate-merchant
openapi: 3.0.1
info:
  title: Nayax Ecom SDK API
  version: v1
  description: >-
    This OpenAPI specification describes the Nayax SDK API, designed to
    facilitate e-commerce transactions, including initialization, payment
    processing, and card token management. It supports various transaction types
    such as Customer-Initiated Transactions (CIT), Merchant-Initiated
    Transactions (MIT), and Card-on-File (COF) operations. The API focuses on
    secure authentication, efficient transaction flows, and real-time status
    updates, with robust error handling and logging capabilities.
servers:
  - url: https://api.nayax.com/sdk
    description: Production Nayax SDK API
security:
  - BearerAuth: []
tags:
  - name: Payments
    description: Operations related to the Nayax SDK API for e-commerce transactions.
  - name: Testing
    description: Endpoints for testing connectivity.
paths:
  /validate-merchant:
    post:
      tags:
        - Management
      summary: Validate Merchant (Start Authentication)
      requestBody:
        description: Request to validate the merchant and initiate authentication.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateMerchantRequest'
            examples:
              validateMerchantRequest:
                summary: Example Validate Merchant Request
                value:
                  tokenId: 116383
                  actorId: someActorId
                  machineId: '0434334921100366'
                  random: 123456789qwertyui
                  cipher: >-
                    X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trBuNJwBEjgBzKhhgpJ5ggnw=
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              examples:
                validateMerchantResponseApproved:
                  summary: Example Validate Merchant Response (Approved)
                  value:
                    verdict: Approved
                    code: 0
                    statusMessage: Merchant authenticated successfully.
                    customDeclineCode: >-
                      9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7
                validateMerchantResponseDeclined:
                  summary: Example Validate Merchant Response (Declined)
                  value:
                    verdict: Declined
                    code: 33
                    statusMessage: Fail to Authenticate
                    customDeclineCode: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              examples:
                badRequest:
                  summary: Bad Request Example
                  value:
                    verdict: Declined
                    code: 997
                    statusMessage: Did not receive mandatory parameters.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              examples:
                unauthorized:
                  summary: Unauthorized Example
                  value:
                    verdict: Declined
                    code: 984
                    statusMessage: Unauthorized – Token is not valid.
components:
  schemas:
    ValidateMerchantRequest:
      type: object
      description: Request body for validating a merchant and initiating authentication.
      properties:
        tokenId:
          type: integer
          format: int32
          nullable: true
          description: Token ID provided by Nayax to the VAS.
          example: 116383
        actorId:
          type: string
          nullable: true
          description: The unique identifier for the actor/integrator.
          example: someActorId
        machineId:
          type: string
          nullable: true
          description: Machine ID allocated in the Nayax Backoffice.
          example: '0434334921100366'
        random:
          type: string
          nullable: true
          description: >-
            A 27-character random string generated by Nayax and sent to the
            Integrator.
          example: 123456789qwertyui
        cipher:
          type: string
          nullable: true
          description: >-
            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=
      additionalProperties: false
    Status:
      type: object
      description: General status object for API responses.
      properties:
        verdict:
          type: string
          nullable: true
          description: Const string values 'Approved' or 'Declined'.
          example: Approved
        code:
          type: integer
          format: int32
          description: Response code. 0 for Approved, relevant decline code for Declined.
          example: 0
        statusMessage:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            Optional. Session status message free text field or additional
            varying data.
          example: Transaction processed successfully.
        customDeclineCode:
          type: string
          nullable: true
          description: >-
            Custom decline code, can also be used to return the
            HashedEcomTransactionId for validate-merchant success.
          example: 9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7
      additionalProperties: false
      required:
        - verdict
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.