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

# Onboard Machine

Registers or updates a vending machine's configuration in the system. This endpoint manages the onboarding of specific machines by linking them to an operator and distributor. It configures the machine's details and returns its unique credentials (such as TerminalId or QrString) along with the final setup status.


## OpenAPI

````yaml /openapi/cortina.yaml post /OnboardMachine
openapi: 3.0.1
info:
  description: Credit Card, Prepaid, DynamicQR, StaticQR APIs
  title: Nayax Cortina API
  version: v2.1
  x-logo:
    url: https://www.nayax.com//wp-content/uploads/2015/10/logo_dark1.png
servers:
  - url: https://{domain}:{port}
    variables:
      domain:
        default: example.com
        description: Customer ID assigned by the service provider
      port:
        default: '443'
        enum:
          - '443'
          - '8443'
security: []
paths:
  /OnboardMachine:
    post:
      tags:
        - Cortina Onboarding
      summary: Onboard Machine
      requestBody:
        content:
          application/*+json:
            schema:
              $ref: '#/components/schemas/OnboardMachineRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardMachineRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/OnboardMachineRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardMachineResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/OnboardMachineResponse'
          description: Success
components:
  schemas:
    OnboardMachineRequest:
      properties:
        ActorInfo:
          $ref: '#/components/schemas/OnboardActorInfo'
        CustomData:
          $ref: '#/components/schemas/OnboardCustomData'
        DistributorInfo:
          $ref: '#/components/schemas/OnboardDistributorInfo'
        MachineInfo:
          $ref: '#/components/schemas/OnboardMachineInfo'
        OnboardingBasicInfo:
          $ref: '#/components/schemas/OnboardingBasicInfo'
        OperatorInfo:
          $ref: '#/components/schemas/OnboardOperatorInfo'
        UpdateInfo:
          $ref: '#/components/schemas/OnboardUpdateInfo'
      type: object
    OnboardMachineResponse:
      properties:
        MachineOnboardingData:
          $ref: '#/components/schemas/MachineOnboardingData'
        OnboardStatus:
          $ref: '#/components/schemas/OnboardStatus'
      type: object
    OnboardActorInfo:
      additionalProperties: false
      description: Actor info for onboarding
      properties:
        ApiKey:
          description: |
            - Optional
            - Length: 40
          type: string
        AppId:
          description: |
            - Optional
            - Length: 250
          type: string
        CertPass:
          description: |
            - Optional
            - Length: 250
          type: string
        CertPath:
          description: |
            - Optional
            - Length: 250
          type: string
        ContactName:
          description: |
            - Optional
            - Length: 200
          type: string
        Country:
          $ref: '#/components/schemas/OnboardCountryInfo'
        DynamicURL:
          description: |
            - Optional, support different url's.
            - Length: 255
            - Actor level url configuration
          type: string
        GeoLocation:
          $ref: '#/components/schemas/OnboardGeoLocation'
        Id:
          description: |
            - Optional
            - Length: 255
            - Actor ID as saved as defined in the Nayax backoffice
          format: int64
          type: integer
        Key:
          description: |
            - Optional
            - Length: 250
          type: string
        MCC:
          description: >
            - Optional

            - classify merchants and businesses by the type of goods or services
            provided. Payment brands, issuers and acquirers.
          format: int32
          type: integer
        MerchantContactMobile:
          description: |
            - Optional
          format: int32
          type: integer
        MerchantContactPhone:
          description: |
            - Optional
          format: int32
          type: integer
        MerchantEmail:
          description: |
            - Optional
            - Length: 400
          type: string
        MerchantId:
          description: |
            - Optional, Contact Nayax TPOC to define.
            - Length: 255
            - Merchant identifier as defined in the Nayax backoffice
          type: string
        MerchantMobileCountryCode:
          description: |
            - Optional
          format: int32
          type: integer
        MerchantPhoneCountryCode:
          description: |
            - Optional
          format: int32
          type: integer
        Name:
          description: |
            - Optional
            - Length: 255
            - Direct Merchant name as defined in the Nayax backoffice
          type: string
        OnboardingStatus:
          $ref: '#/components/schemas/OnboardingStatusEnum'
        OperatorId:
          description: |
            - Optional
            - Length: 255
            - Merchant Operator ID as defined in the Nayax backoffice
          format: int64
          type: integer
        OperatorName:
          description: |
            - Optional
            - Length: 255
            - Merchant Operator name  as defined in the Nayax backoffice
          type: string
        Password:
          description: |
            - Optional
            - Length: 50
          type: string
        SubMerchantId:
          description: |
            - Optional
            - Length: 50
          type: string
        SubMerchantNumber:
          description: |
            - Optional
          format: int32
          type: integer
        TerminalId:
          description: |
            - Optional
            - Length: 255
          type: string
        URL:
          description: |
            - Optional
            - Length: 250
          type: string
        UserName:
          description: |
            - Optional
            - Length: 40
          type: string
      type: object
    OnboardCustomData:
      additionalProperties: false
      description: Custom Fields Information, Contact Nayax TPOC to define.
      properties:
        Actor:
          description: |
            Actor custom data (String in json format)
          type: string
        DirectActor:
          description: |
            Direct actor custom data (String in json format)
          type: string
        Distributor:
          description: |
            Distributor custom data (String in json format)
          type: string
        Machine:
          description: |
            Machine custom data (String in json format)
          type: string
        Operator:
          description: |
            Operator custom data (String in json format)
          type: string
      type: object
    OnboardDistributorInfo:
      additionalProperties: false
      description: Distributor info for onboarding
      properties:
        ApiKey:
          description: |
            - Optional
            - Length: 40
          type: string
        AppId:
          description: |
            - Optional
            - Length: 250
          type: string
        CertPass:
          description: |
            - Optional
            - Length: 250
          type: string
        CertPath:
          description: |
            - Optional
            - Length: 250
          type: string
        Country:
          $ref: '#/components/schemas/OnboardCountryInfo'
        DynamicURL:
          description: |
            - Optional, support different url's.
            - Length: 255
            - Actor level url configuration
          type: string
        GeoLocation:
          $ref: '#/components/schemas/OnboardGeoLocation'
        Id:
          description: |
            - Optional
            - Length: 255
            - Actor ID as saved as defined in the Nayax backoffice
          format: int64
          type: integer
        Key:
          description: |
            - Optional
            - Length: 250
          type: string
        MCC:
          description: >
            - Optional

            - classify merchants and businesses by the type of goods or services
            provided. Payment brands, issuers and acquirers.
          format: int32
          type: integer
        MerchantId:
          description: |
            - Optional, Contact Nayax TPOC to define.
            - Length: 255
            - Merchant identifier as defined in the Nayax backoffice
          type: string
        Name:
          description: |
            - Optional
            - Length: 255
            - Direct Merchant name as defined in the Nayax backoffice
          type: string
        OnboardingStatus:
          $ref: '#/components/schemas/OnboardingStatusEnum'
        OperatorId:
          description: |
            - Optional
            - Length: 255
            - Merchant Operator ID as defined in the Nayax backoffice
          format: int64
          type: integer
        OperatorName:
          description: |
            - Optional
            - Length: 255
            - Merchant Operator name  as defined in the Nayax backoffice
          type: string
        Password:
          description: |
            - Optional
            - Length: 50
          type: string
        SubMerchantId:
          description: |
            - Optional
            - Length: 50
          type: string
        SubMerchantNumber:
          description: |
            - Optional
          format: int32
          type: integer
        TerminalId:
          description: |
            - Optional
            - Length: 255
          type: string
        URL:
          description: |
            - Optional
            - Length: 250
          type: string
        UserName:
          description: |
            - Optional
            - Length: 40
          type: string
      type: object
    OnboardMachineInfo:
      additionalProperties: false
      description: Machine info for onboarding
      properties:
        City:
          description: |
            - Optional
            - Length: 255
            - Machine City as defined in the Nayax backoffice
          type: string
        Country:
          $ref: '#/components/schemas/OnboardCountryInfo'
        ExternalId:
          description: >
            - Optional

            - Length: 200

            - Optional filed, it reflects the Machine External ID as it has been
            provided by the operator in the Nayax back-office system (Machine
            number - operator).
          type: string
        GeoLocation:
          $ref: '#/components/schemas/OnboardGeoLocation'
        GroupId:
          type: string
        Id:
          description: |
            - Mandatory
            - Machine entity unique ID allocated in the Nayax backoffice.
          format: int64
          type: integer
        Name:
          description: |
            - Mandatory
            - Length: 255
            - Machine Name as defined in the Nayax backoffice
          type: string
        Offset:
          description: |
            - Optional
            - Length: 255
            - UTC timezone offset
          type: string
        OnboardingStatus:
          $ref: '#/components/schemas/OnboardingStatusEnum'
        OperatorId:
          description: |
            - Optional
            - Length: 255
            - Merchant ID as defined in the Nayax backoffice
          type: string
        Password:
          description: |
            - Optional
            - Length: 25
          type: string
        QrString:
          description: |
            - Optional
          type: string
        Region:
          description: |
            - Optional
            - Length: 255
            - Region as defined in the Nayax backoffice
          type: string
        TerminalId:
          description: |
            - Optional, Contact Nayax TPOC to define.
            - Length: 255
            - Optinal Terminal identifier as deifned in the Nayax backoffice.
          type: string
        Type:
          description: |
            - Length: 50
            - Machine Type as defined in the Nayax backoffice
          type: string
        UserName:
          description: |
            - Optional
            - Length: 40
          type: string
        ZipCode:
          description: |
            - Optional
            - Length: 255
            - Machine ZipCode as defined in the Nayax backoffice
          type: string
      type: object
    OnboardingBasicInfo:
      additionalProperties: false
      description: Describing the onboarding Operation details
      properties:
        BillingProviderID:
          description: |
            - Mandatory
          format: int16
          type: integer
        OnboardingOperation:
          description: |
            Indicates the possible onboarding operation:
                1 - Register
                2 - Unregister
                3 - Update
                4 - GetStatus
             - enum
             - Mandatory
             - Indicates the possible onboarding operation.
          enum:
            - 1
            - 2
            - 3
            - 4
          format: int32
          type: integer
        OnboardingRequestId:
          description: |
            - Mandatory
            - GUID Generated by Nayax
          type: integer
        OnboardingTransactionId:
          description: |
            - TransactionId from provider
          format: int32
          type: integer
        PaymentMethodID:
          description: |
            - Mandatory
          format: int16
          type: integer
        RequestTime:
          description: |
            - Mandatory
            - The date time string of when the Onboarding took place
            - Format: ddMMyyHHmmss
          type: string
        SiteId:
          description: Mandatory
          format: int16
          type: integer
        TimeoutMS:
          format: int32
          type: integer
        TransactionID:
          description: |
            - Mandatory
            - Generated by the integrator on startSession
          format: int16
          type: integer
      type: object
    OnboardOperatorInfo:
      additionalProperties: false
      description: Operator info for onboarding
      properties:
        ApiKey:
          description: |
            - Optional
            - Length: 40
          type: string
        AppId:
          description: |
            - Optional
            - Length: 250
          type: string
        CertPass:
          description: |
            - Optional
            - Length: 250
          type: string
        CertPath:
          description: |
            - Optional
            - Length: 250
          type: string
        Country:
          $ref: '#/components/schemas/OnboardCountryInfo'
        DynamicURL:
          description: |
            - Optional, support different url's.
            - Length: 255
            - Actor level url configuration
          type: string
        GeoLocation:
          $ref: '#/components/schemas/OnboardGeoLocation'
        Id:
          description: |
            - Optional
            - Length: 255
            - Actor ID as saved as defined in the Nayax backoffice
          format: int64
          type: integer
        Key:
          description: |
            - Optional
            - Length: 250
          type: string
        MCC:
          description: >
            - Optional

            - classify merchants and businesses by the type of goods or services
            provided. Payment brands, issuers and acquirers.
          format: int32
          type: integer
        MerchantId:
          description: |
            - Optional, Contact Nayax TPOC to define.
            - Length: 255
            - Merchant identifier as defined in the Nayax backoffice
          type: string
        Name:
          description: |
            - Optional 
            - Length: 255
            - Direct Merchant name as defined in the Nayax backoffice
          type: string
        OnboardingStatus:
          $ref: '#/components/schemas/OnboardingStatusEnum'
        OperatorId:
          description: |
            - Optional
            - Length: 255
            - Merchant Operator ID as defined in the Nayax backoffice
          format: int64
          type: integer
        OperatorName:
          description: |
            - Optional
            - Length: 255
            - Merchant Operator name  as defined in the Nayax backoffice
          type: string
        Password:
          description: |
            - Optional
            - Length: 50
          type: string
        SubMerchantId:
          description: |
            - Optional
            - Length: 50
          type: string
        SubMerchantNumber:
          description: |
            - Optional
          format: int32
          type: integer
        TerminalId:
          description: |
            - Optional
            - Length: 255
          type: string
        URL:
          description: |
            - Optional
            - Length: 250
          type: string
        UserName:
          description: |
            - Optional
            - Length: 40
          type: string
      type: object
    OnboardUpdateInfo:
      additionalProperties: false
      items:
        type: string
      type: array
    MachineOnboardingData:
      additionalProperties: false
      description: Echo and/or Updated onboarding machine data
      properties:
        ActorId:
          description: |
            - Optional
          format: int64
          type: integer
        CustomData:
          $ref: '#/components/schemas/OnboardCustomData'
        MachineId:
          description: |
            - Optional
          format: int64
          type: integer
        Password:
          description: |
            - Optional
            - Length: 25
          type: string
        QrString:
          description: |
            - Optional
          type: string
        TerminalId:
          description: |
            - Optional
            - Length: 255
          type: string
        UserName:
          description: |
            - Optional
            - Length: 40
          type: string
      type: object
    OnboardStatus:
      additionalProperties: false
      description: Transaction status
      properties:
        Code:
          description: |
            Indicates the onboarding status:
                0 - Null-none
                1 - Pending
                2 - Success
                3 - Failed
                4 - Expired
                5 - Skip
             - enum
             - Mandatory
             - Indicates the onboarding status.
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
          format: int32
          type: integer
        StatusMessage:
          description: >
            - Optional

            - Length: 255

            - Onboarding status message free text field / additional varying
            data
          type: string
        Verdict:
          description: |
            - Mandatory
            - Const string values:
            - Status of the request ('Approved'/'Declined')
          type: string
      type: object
    OnboardCountryInfo:
      additionalProperties: false
      description: |
        Actor and Machine Country information
      properties:
        Alpha2Code:
          description: |
            String(2)
            Mandatory
            ISO-3166-1 format: Alpha-2 code
          type: string
        Alpha3Code:
          description: |
            String(3)
            Mandatory
            ISO-3166-1 format: Alpha-3 code
          type: string
        Name:
          description: |
            String
            Mandatory
            Country Full Name
          type: string
        NumericCode:
          description: |
            String(3)
            Mandatory
            ISO-3166-1 format: Numeric-3 code
          type: string
      type: object
    OnboardGeoLocation:
      additionalProperties: false
      description: Actor and Machine Geo location information
      properties:
        Address:
          description: |
            String(255)
            Optional
            Address as defined in the Nayax backoffice
          type: string
        City:
          description: |
            - String(255)
            - Optional
            - City as defined in the Nayax backoffice
          type: string
        CountryCode:
          description: |
            String
            Optional
            Country code (ISO3) as defined in the Nayax backoffice
          type: string
        Latitude:
          description: |
            - Machine Location Latitude as defined in the Nayax backoffice
          format: double
          type: number
        Longitude:
          description: |
            - Machine Location Longitude as defined in the Nayax backoffice
          format: double
          type: number
        State:
          description: |
            - String
            - Optional
            - Actor geo state code as defined in the Nayax backoffice
          type: string
        ZipCode:
          description: |
            String(255)
            Optional
            Zip code defined in the Nayax backoffice
          type: string
      type: object
    OnboardingStatusEnum:
      description: |
        * 0 - None
        * 1 - Pending
        * 2 - Success
        * 3 - Failed
        * 4 - Expired
        * 5 - Skip
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
      format: int32
      type: integer

````