Adyen
Adyen Terminals API

The Terminals API from Adyen — 5 operation(s) for terminals.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Terminals API
  description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
  x-timestamp: '2023-05-30T15:27:20Z'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: Terminals
paths:
  /terminals:
    get:
      tags:
      - Terminals
      summary: Adyen Get a List of Terminals
      description: "Returns the payment terminals that the API credential has access to and that match the query parameters. \nTo make this request, your API credential must have the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):\n* Management API — Terminal actions read"
      operationId: get-terminals
      x-sortIndex: 1
      x-methodName: listTerminals
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: Returns terminals with an ID that contains the specified string. If present, other query parameters are ignored.
        name: searchQuery
        in: query
        required: false
        schema:
          type: string
      - description: Returns one or more terminals associated with the one-time passwords specified in the request. If this query parameter is used, other query parameters are ignored.
        name: otpQuery
        in: query
        required: false
        schema:
          type: string
      - description: Returns terminals located in the countries specified by their [two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
        name: countries
        in: query
        required: false
        schema:
          type: string
      - description: Returns terminals that belong to the merchant accounts specified by their unique merchant account ID.
        name: merchantIds
        in: query
        required: false
        schema:
          type: string
      - description: Returns terminals that are assigned to the [stores](https://docs.adyen.com/api-explorer/#/ManagementService/latest/get/stores) specified by their unique store ID.
        name: storeIds
        in: query
        required: false
        schema:
          type: string
      - description: Returns terminals of the [models](https://docs.adyen.com/api-explorer/#/ManagementService/latest/get/companies/{companyId}/terminalModels) specified in the format *brand.model*.
        name: brandModels
        in: query
        required: false
        schema:
          type: string
      - description: The number of the page to fetch.
        name: pageNumber
        in: query
        required: false
        schema:
          format: int32
          type: integer
      - description: The number of items to have on a page, maximum 100. The default is 20 items on a page.
        name: pageSize
        in: query
        required: false
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/get-terminals-success-200'
              schema:
                $ref: '#/components/schemas/ListTerminalsResponse'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals400Example:
                  summary: Default get-terminals 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals401Example:
                  summary: Default get-terminals 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals403Example:
                  summary: Default get-terminals 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals422Example:
                  summary: Default get-terminals 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals500Example:
                  summary: Default get-terminals 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /terminals/scheduleActions:
    post:
      tags:
      - Terminals
      summary: Adyen Create a Terminal Action
      description: "Schedules a [terminal action](https://docs.adyen.com/point-of-sale/automating-terminal-management/terminal-actions-api) by specifying the action and the terminals that the action must be applied to. \n\nThe following restrictions apply:\n* You can schedule only one action at a time. For example, to install a new app version and remove an old app version, you have to make two API requests. \n* The maximum number of terminals in a request is **100**. For example, to apply an action to 250 terminals, you have to divide the terminals over three API requests. \n* If there is an error with one or more terminal IDs in the request, the action is scheduled for none of the terminals. You need to fix the error and try again. \n\nTo make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#api-permissions):\n* Management API—Terminal actions read and write"
      operationId: post-terminals-scheduleActions
      x-sortIndex: 1
      x-methodName: createTerminalAction
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              install-app:
                $ref: '#/components/examples/post-terminals-scheduleActions-install-app'
              uninstall-cert:
                $ref: '#/components/examples/post-terminals-scheduleActions-uninstall-cert'
              verification-error:
                $ref: '#/components/examples/post-terminals-scheduleActions-verification-error'
            schema:
              $ref: '#/components/schemas/ScheduleTerminalActionsRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                install-app:
                  $ref: '#/components/examples/post-terminals-scheduleActions-install-app-200'
                uninstall-cert:
                  $ref: '#/components/examples/post-terminals-scheduleActions-uninstall-cert-200'
              schema:
                $ref: '#/components/schemas/ScheduleTerminalActionsResponse'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-scheduleActions400Example:
                  summary: Default post-terminals-scheduleActions 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-scheduleActions401Example:
                  summary: Default post-terminals-scheduleActions 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-scheduleActions403Example:
                  summary: Default post-terminals-scheduleActions 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              examples:
                verification-error:
                  $ref: '#/components/examples/post-terminals-scheduleActions-verification-error-422'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-scheduleActions500Example:
                  summary: Default post-terminals-scheduleActions 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /terminals/{terminalId}/reassign:
    post:
      tags:
      - Terminals
      summary: Adyen Reassign a Terminal
      description: 'Reassigns a payment terminal to a company account, merchant account, merchant account inventory, or a store.


        To make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—Assign Terminal'
      x-addedInVersion: '3'
      operationId: post-terminals-terminalId-reassign
      x-sortIndex: 2
      x-methodName: reassignTerminal
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminalReassignmentRequest'
      parameters:
      - description: The unique identifier of the payment terminal.
        name: terminalId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'No Content - look at the actual response code for the status of the request. '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-terminalId-reassign400Example:
                  summary: Default post-terminals-terminalId-reassign 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-terminalId-reassign401Example:
                  summary: Default post-terminals-terminalId-reassign 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-terminalId-reassign403Example:
                  summary: Default post-terminals-terminalId-reassign 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-terminalId-reassign422Example:
                  summary: Default post-terminals-terminalId-reassign 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-terminals-terminalId-reassign500Example:
                  summary: Default post-terminals-terminalId-reassign 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /terminals/{terminalId}/terminalLogos:
    get:
      tags:
      - Terminals
      summary: Adyen Get the Terminal Logo
      description: 'Returns the logo that is configured for the payment terminal identified in the path.

        The logo is returned as a Base64-encoded string. You need to Base64-decode the string to get the actual image file.


        To make this request, your API credential must have one of the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—Terminal settings read

        * Management API—Terminal settings read and write'
      operationId: get-terminals-terminalId-terminalLogos
      x-sortIndex: 4
      x-methodName: getTerminalLogo
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the payment terminal.
        name: terminalId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/get-terminals-terminalId-terminalLogos-success-200'
              schema:
                $ref: '#/components/schemas/Logo'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals-terminalId-terminalLogos400Example:
                  summary: Default get-terminals-terminalId-terminalLogos 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals-terminalId-terminalLogos401Example:
                  summary: Default get-terminals-terminalId-terminalLogos 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals-terminalId-terminalLogos403Example:
                  summary: Default get-terminals-terminalId-terminalLogos 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals-terminalId-terminalLogos422Example:
                  summary: Default get-terminals-terminalId-terminalLogos 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-terminals-terminalId-terminalLogos500Example:
                  summary: Default get-terminals-terminalId-terminalLogos 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      tags:
      - Terminals
      summary: Adyen Update the Logo
      description: 'Updates the logo for the payment terminal identified in the path.


        * To change the logo, specify the image file as a Base64-encoded string.

        * To restore the logo inherited from a higher level (store, merchant account, or company account), specify an empty logo value.


        To make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—Terminal settings read and write'
      operationId: patch-terminals-terminalId-terminalLogos
      x-sortIndex: 6
      x-methodName: updateLogo
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              remove-logo:
                $ref: '#/components/examples/patch-terminals-terminalId-terminalLogos-remove-logo'
              upload-logo:
                $ref: '#/components/examples/patch-terminals-terminalId-terminalLogos-upload-logo'
            schema:
              $ref: '#/components/schemas/Logo'
      parameters:
      - description: The unique identifier of the payment terminal.
        name: terminalId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                remove-logo:
                  $ref: '#/components/examples/patch-terminals-terminalId-terminalLogos-remove-logo-200'
                upload-logo:
                  $ref: '#/components/examples/patch-terminals-terminalId-terminalLogos-upload-logo-200'
              schema:
                $ref: '#/components/schemas/Logo'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                patch-terminals-terminalId-terminalLogos400Example:
                  summary: Default patch-terminals-terminalId-terminalLogos 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                patch-terminals-terminalId-terminalLogos401Example:
                  summary: Default patch-terminals-terminalId-terminalLogos 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                patch-terminals-terminalId-terminalLogos403Example:
                  summary: Default patch-terminals-terminalId-terminalLogos 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                patch-terminals-terminalId-terminalLogos422Example:
                  summary: Default patch-terminals-terminalId-terminalLogos 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                patch-terminals-terminalId-terminalLogos500Example:
                  summary: Default patch-terminals-terminalId-terminalLogos 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        d

# --- truncated at 32 KB (102 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-terminals-api-openapi.yml
Adyen Terminals API

Documentation

Specifications

Other Resources

OpenAPI Specification
