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

Registers or updates a merchant (Actor) in the system. This endpoint handles the onboarding process for new merchants, distributors, or operators. It accepts their profile details and configuration settings and returns an onboarding status (e.g., Success, Pending, Failed) along with credentials such as API keys or merchant IDs.


## OpenAPI

````yaml /openapi/cortina.yaml post /OnboardActor
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:
  /OnboardActor:
    post:
      tags:
        - Cortina Onboarding
      summary: Onboard Actor
      requestBody:
        content:
          application/*+json:
            schema:
              $ref: '#/components/schemas/OnboardActorRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardActorRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/OnboardActorRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardActorResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/OnboardActorResponse'
          description: Success
components:
  schemas:
    OnboardActorRequest:
      properties:
        ActorInfo:
          $ref: '#/components/schemas/OnboardActorInfo'
        CustomData:
          $ref: '#/components/schemas/OnboardCustomData'
        DistributorInfo:
          $ref: '#/components/schemas/OnboardDistributorInfo'
        OnboardingBasicInfo:
          $ref: '#/components/schemas/OnboardingBasicInfo'
        OperatorInfo:
          $ref: '#/components/schemas/OnboardOperatorInfo'
        UpdateInfo:
          $ref: '#/components/schemas/OnboardUpdateInfo'
      type: object
    OnboardActorResponse:
      properties:
        ActorOnboardingData:
          $ref: '#/components/schemas/ActorOnboardingData'
        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
    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
    ActorOnboardingData:
      additionalProperties: false
      description: Echo and/or Updated onboarding actor data (Merchant data)
      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
        CustomData:
          $ref: '#/components/schemas/OnboardCustomData'
        Key:
          description: |
            - Optional
            - Length: 250
          type: string
        MerchantId:
          description: |
            - Optional
            - Length: 40
          type: string
        OnboardingTransactionId:
          description: |
            - Optional
          format: int32
          type: integer
        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
    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

````