> ## 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.

# StartSession

This is the initial API call sent by Nayax. It initiates the transaction session by authenticating both parties and generating a `SparkTransactionId`, which will be echoed in all subsequent calls throughout the transaction's lifecycle.

> [card] [Try it: Spark Auth Tool](https://devzone.nayax.com/docs/integrate-pos-device/spark/security-authentication/spark-auth-tool.md#startsession)
>
> Build or inspect the `StartSession` cipher in your browser, no code required. Opens the tool on the StartSession tab.


## OpenAPI

````yaml /openapi/zh/spark.yaml post /StartSession
openapi: 3.0.1
info:
  title: Nayax Spark API
  description: RemoteStart V2
  version: v2
servers:
  - url: https://nayax-spark-dmz.nayax.com/api
    description: The same host serves the integration and production environments.
security: []
tags:
  - name: Transactions
paths:
  /StartSession:
    servers:
      - url: https://{domain}/api
        variables:
          domain:
            default: nayax-spark-dmz.nayax.com
            description: >-
              The Integrator hosts this endpoint. Nayax sends the call to the
              callback URL configured during onboarding.
    post:
      tags:
        - Transactions
      summary: StartSession
      requestBody:
        description: The payload to initiate a new session.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSessionRequest'
      responses:
        '200':
          description: Success. A new session has been successfully initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartSessionResponse'
components:
  schemas:
    StartSessionRequest:
      type: object
      nullable: true
      description: >
        The request payload sent by the Spark platform to the integrator's
        configured `StartSession` endpoint to initiate a transaction session.
      properties:
        HwSerial:
          type: string
          nullable: false
          description: |
            The serial number of the payment terminal hardware.
        MachineId:
          type: integer
          format: int64
          description: |
            The unique identifier for the Nayax machine.
        TokenId:
          type: integer
          format: int32
          description: |
            A unique token provided by Nayax for secure authentication.
        Random:
          type: string
          nullable: false
          description: |
            A random alphanumeric string used for session verification.
      example:
        HwSerial: '0434334921100366'
        MachineId: 71234996
        TokenId: 116383
        Random: 123456789qwertyui
    StartSessionResponse:
      type: object
      nullable: true
      description: >
        The response payload from the `StartSession` endpoint, containing
        encrypted data and the session status.
      properties:
        Cipher:
          type: string
          nullable: false
          description: |
            The encrypted data used to authenticate and initiate the session.
        SparkTransactionId:
          type: string
          nullable: true
          description: >
            The unique identifier for this transaction, which is echoed in all
            subsequent calls throughout the transaction's lifecycle.
        Status:
          $ref: '#/components/schemas/Status'
      example:
        Cipher: >-
          X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trzBuNJwBEjgBzKhhgpJ5ggnw=
        Status:
          Verdict: Approved
    Status:
      type: object
      nullable: false
      description: 交易状态详情
      properties:
        Verdict:
          type: string
          nullable: false
          description: 请求的状态（Approved / Declined）
        ErrorCode:
          type: integer
          format: int16
          nullable: true
          description: |
            - 条件必填
            - 请求被拒绝的原因
        ErrorDescription:
          type: string
          nullable: true
          description: |
            - 条件必填
            - 长度：255
            - 错误描述
        StatusMessage:
          type: string
          nullable: true
          description: |
            - 可选
            - 长度：255
            - 交易状态消息，自由文本字段

````

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