This API provides endpoints for managing your point-of-sale (POS) payment terminals. You can use the API to obtain information about a specific terminal, retrieve overviews of your terminals and stores, and assign terminals to a merchant account or store.
openapi: 3.1.0
servers:
- url: https://postfmapi-test.adyen.com/postfmapi/terminal/v1
info:
version: '1'
x-publicVersion: true
title: Adyen POS Terminal Management API
description: >-
This API provides endpoints for managing your point-of-sale (POS) payment
terminals. You can use the API to obtain information about a specific
terminal, retrieve overviews of your terminals and stores, and assign
terminals to a merchant account or store.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: assignTerminals
- name: findTerminal
- name: getStoresUnderAccount
- name: getTerminalDetails
- name: getTerminalsUnderAccount
paths:
/assignTerminals:
post:
tags:
- assignTerminals
summary: Adyen Assign Terminals
description: >-
Assigns one or more payment terminals to a merchant account or a store.
You can also use this endpoint to reassign terminals between merchant
accounts or stores, and to unassign a terminal and return it to company
inventory.
operationId: post-assignTerminals
x-sortIndex: 1
x-methodName: assignTerminals
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
assignTerminalCompany:
$ref: >-
#/components/examples/post-assignTerminals-assignTerminalCompany
assignTerminalMerchant:
$ref: >-
#/components/examples/post-assignTerminals-assignTerminalMerchant
assignTerminalStore:
$ref: '#/components/examples/post-assignTerminals-assignTerminalStore'
schema:
$ref: '#/components/schemas/AssignTerminalsRequest'
responses:
'200':
content:
application/json:
examples:
assignTerminalCompany:
$ref: >-
#/components/examples/post-assignTerminals-assignTerminalCompany-200
assignTerminalMerchant:
$ref: >-
#/components/examples/post-assignTerminals-assignTerminalMerchant-200
assignTerminalStore:
$ref: >-
#/components/examples/post-assignTerminals-assignTerminalStore-200
schema:
$ref: '#/components/schemas/AssignTerminalsResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-assignTerminals401Example:
summary: Default post-assignTerminals 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/findTerminal:
post:
tags:
- findTerminal
summary: Adyen Get the Account or Store of a Terminal
description: >-
Returns the company account, merchant account, or store that a payment
terminal is assigned to.
operationId: post-findTerminal
x-sortIndex: 1
x-methodName: findTerminal
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
findTerminal:
$ref: '#/components/examples/post-findTerminal-findTerminal'
schema:
$ref: '#/components/schemas/FindTerminalRequest'
responses:
'200':
content:
application/json:
examples:
findTerminal:
$ref: '#/components/examples/post-findTerminal-findTerminal-200'
schema:
$ref: '#/components/schemas/FindTerminalResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-findTerminal401Example:
summary: Default post-findTerminal 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/getStoresUnderAccount:
post:
tags:
- getStoresUnderAccount
summary: Adyen Get the Stores of an Account
description: >-
Returns a list of stores associated with a company account or a merchant
account, including the status of each store.
operationId: post-getStoresUnderAccount
x-sortIndex: 1
x-methodName: getStoresUnderAccount
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
getStoresCompany:
$ref: >-
#/components/examples/post-getStoresUnderAccount-getStoresCompany
getStoresMerchant:
$ref: >-
#/components/examples/post-getStoresUnderAccount-getStoresMerchant
schema:
$ref: '#/components/schemas/GetStoresUnderAccountRequest'
responses:
'200':
content:
application/json:
examples:
getStoresCompany:
$ref: >-
#/components/examples/post-getStoresUnderAccount-getStoresCompany-200
getStoresMerchant:
$ref: >-
#/components/examples/post-getStoresUnderAccount-getStoresMerchant-200
schema:
$ref: '#/components/schemas/GetStoresUnderAccountResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getStoresUnderAccount401Example:
summary: Default post-getStoresUnderAccount 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/getTerminalDetails:
post:
tags:
- getTerminalDetails
summary: Adyen Get the Details of a Terminal
description: >-
Returns the details of a payment terminal, including where the terminal
is assigned to. The response returns the same details that are provided
in the terminal list in your Customer Area and in the Terminal Fleet
report.
operationId: post-getTerminalDetails
x-sortIndex: 1
x-methodName: getTerminalDetails
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
getTerminalDetails:
$ref: >-
#/components/examples/post-getTerminalDetails-getTerminalDetails
schema:
$ref: '#/components/schemas/GetTerminalDetailsRequest'
responses:
'200':
content:
application/json:
examples:
getTerminalDetails:
$ref: >-
#/components/examples/post-getTerminalDetails-getTerminalDetails-200
schema:
$ref: '#/components/schemas/GetTerminalDetailsResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getTerminalDetails401Example:
summary: Default post-getTerminalDetails 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/getTerminalsUnderAccount:
post:
tags:
- getTerminalsUnderAccount
summary: Adyen Get the List of Terminals
description: >-
Returns a list of payment terminals associated with a company account,
merchant account, or store. The response shows whether the terminals are
in the inventory, or in-store (ready for boarding or already boarded).
operationId: post-getTerminalsUnderAccount
x-sortIndex: 1
x-methodName: getTerminalsUnderAccount
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
getTerminalsCompany:
$ref: >-
#/components/examples/post-getTerminalsUnderAccount-getTerminalsCompany
getTerminalsMerchant:
$ref: >-
#/components/examples/post-getTerminalsUnderAccount-getTerminalsMerchant
getTerminalsStore:
$ref: >-
#/components/examples/post-getTerminalsUnderAccount-getTerminalsStore
schema:
$ref: '#/components/schemas/GetTerminalsUnderAccountRequest'
responses:
'200':
content:
application/json:
examples:
getTerminalsCompany:
$ref: >-
#/components/examples/post-getTerminalsUnderAccount-getTerminalsCompany-200
getTerminalsMerchant:
$ref: >-
#/components/examples/post-getTerminalsUnderAccount-getTerminalsMerchant-200
getTerminalsStore:
$ref: >-
#/components/examples/post-getTerminalsUnderAccount-getTerminalsStore-200
schema:
$ref: '#/components/schemas/GetTerminalsUnderAccountResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getTerminalsUnderAccount401Example:
summary: Default post-getTerminalsUnderAccount 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Address:
properties:
city:
type: string
countryCode:
type: string
postalCode:
type: string
stateOrProvince:
type: string
streetAddress:
type: string
streetAddress2:
type: string
type: object
AssignTerminalsRequest:
properties:
companyAccount:
description: >-
Your company account. To return terminals to the company inventory,
specify only this parameter and the `terminals`.
type: string
merchantAccount:
description: >-
Name of the merchant account. Specify this parameter to assign
terminals to this merchant account or to a store under this merchant
account.
type: string
merchantInventory:
description: >-
Boolean that indicates if you are assigning the terminals to the
merchant inventory. Do not use when assigning terminals to a store.
Required when assigning the terminal to a merchant account.
- Set this to **true** to assign the terminals to the merchant
inventory. This also means that the terminals cannot be boarded.
- Set this to **false** to assign the terminals to the merchant
account as in-store terminals. This makes the terminals ready to be
boarded and to process payments through the specified merchant
account.
type: boolean
store:
description: >-
The store code of the store that you want to assign the terminals
to.
type: string
terminals:
description: >-
Array containing a list of terminal IDs that you want to assign or
reassign to the merchant account or store, or that you want to
return to the company inventory.
For example, `["V400m-324689776","P400Plus-329127412"]`.
items:
type: string
type: array
required:
- companyAccount
- terminals
type: object
AssignTerminalsResponse:
properties:
results:
additionalProperties:
type: string
description: >-
Array that returns a list of the terminals, and for each terminal
the result of assigning it to an account or store.
The results can be:
- `Done`: The terminal has been assigned.
- `AssignmentScheduled`: The terminal will be assigned asynschronously.
- `RemoveConfigScheduled`: The terminal was previously assigned and boarded. Wait for the terminal to synchronize with the Adyen platform. For more information, refer to [Reassigning boarded
terminals](https://docs.adyen.com/point-of-sale/managing-terminals/assign-terminals#reassign-boarded-terminals).
- `Error`: There was an error when assigning the terminal.
type: object
required:
- results
type: object
FindTerminalRequest:
properties:
terminal:
description: >-
The unique terminal ID in the format `[Device model]-[Serial
number]`.
For example, **V400m-324689776**.
type: string
required:
- terminal
type: object
FindTerminalResponse:
properties:
companyAccount:
description: >-
The company account that the terminal is associated with. If this is
the only account level shown in the response, the terminal is
assigned to the inventory of the company account.
type: string
merchantAccount:
description: >-
The merchant account that the terminal is associated with. If the
response doesn't contain a `store` the terminal is assigned to this
merchant account.
type: string
merchantInventory:
description: >-
Boolean that indicates if the terminal is assigned to the merchant
inventory. This is returned when the terminal is assigned to a
merchant account.
- If **true**, this indicates that the terminal is in the merchant
inventory. This also means that the terminal cannot be boarded.
- If **false**, this indicates that the terminal is assigned to the
merchant account as an in-store terminal. This means that the
terminal is ready to be boarded, or is already boarded.
type: boolean
store:
description: The store code of the store that the terminal is assigned to.
type: string
terminal:
description: The unique terminal ID.
type: string
required:
- companyAccount
- terminal
type: object
GetStoresUnderAccountRequest:
properties:
companyAccount:
description: >-
The company account. If you only specify this parameter, the
response includes the stores of all merchant accounts that are
associated with the company account.
type: string
merchantAccount:
description: >-
The merchant account. With this parameter, the response only
includes the stores of the specified merchant account.
type: string
required:
- companyAccount
type: object
GetStoresUnderAccountResponse:
properties:
stores:
description: >-
Array that returns a list of all stores for the specified merchant
account, or for all merchant accounts under the company account.
items:
$ref: '#/components/schemas/Store'
type: array
type: object
GetTerminalDetailsRequest:
properties:
terminal:
description: >-
The unique terminal ID in the format `[Device model]-[Serial
number]`.
For example, **V400m-324689776**.
type: string
required:
- terminal
type: object
GetTerminalDetailsResponse:
properties:
bluetoothIp:
description: The Bluetooth IP address of the terminal.
type: string
bluetoothMac:
description: The Bluetooth MAC address of the terminal.
type: string
companyAccount:
description: >-
The company account that the terminal is associated with. If this is
the only account level shown in the response, the terminal is
assigned to the inventory of the company account.
type: string
country:
description: The country where the terminal is used.
type: string
deviceModel:
description: The model name of the terminal.
type: string
dhcpEnabled:
description: >-
Indicates whether assigning IP addresses through a DHCP server is
enabled on the terminal.
type: boolean
displayLabel:
description: >-
The label shown on the status bar of the display. This label (if
any) is specified in your Customer Area.
type: string
ethernetIp:
description: The terminal's IP address in your Ethernet network.
type: string
ethernetMac:
description: The terminal's MAC address in your Ethernet network.
type: string
firmwareVersion:
description: The software release currently in use on the terminal.
type: string
iccid:
description: >-
The integrated circuit card identifier (ICCID) of the SIM card in
the terminal.
type: string
lastActivityDateTime:
description: >-
Date and time of the last activity on the terminal. Not included
when the last activity was more than 14 days ago.
format: date-time
type: string
lastTransactionDateTime:
description: >-
Date and time of the last transaction on the terminal. Not included
when the last transaction was more than 14 days ago.
format: date-time
type: string
linkNegotiation:
description: |-
The Ethernet link negotiation that the terminal uses:
- `auto`: Auto-negotiation
- `100full`: 100 Mbps full duplex
type: string
merchantAccount:
description: >-
The merchant account that the terminal is associated with. If the
response doesn't contain a `store` the terminal is assigned to this
merchant account.
type: string
merchantInventory:
description: >-
Boolean that indicates if the terminal is assigned to the merchant
inventory. This is returned when the terminal is assigned to a
merchant account.
- If **true**, this indicates that the terminal is in the merchant
inventory. This also means that the terminal cannot be boarded.
- If **false**, this indicates that the terminal is assigned to the
merchant account as an in-store terminal. This means that the
terminal is ready to be boarded, or is already boarded.
type: boolean
permanentTerminalId:
description: The permanent terminal ID.
type: string
serialNumber:
description: The serial number of the terminal.
type: string
simStatus:
description: >-
On a terminal that supports 3G or 4G connectivity, indicates the
status of the SIM card in the terminal: ACTIVE or INVENTORY.
type: string
store:
description: The store code of the store that the terminal is assigned to.
type: string
storeDetails:
description: The store that the terminal is assigned to.
$ref: '#/components/schemas/Store'
terminal:
description: The unique terminal ID.
type: string
terminalStatus:
description: >-
The status of the terminal:
- `OnlineToday`, `OnlineLast1Day`, `OnlineLast2Days` etcetera to
`OnlineLast7Days`: Indicates when in the past week the terminal was
last online.
- `SwitchedOff`: Indicates it was more than a week ago that the
terminal was last online.
- `ReAssignToInventoryPending`, `ReAssignToStorePending`,
`ReAssignToMerchantInventoryPending`: Indicates the terminal is
scheduled to be reassigned.
enum:
- OnlineLast1Day
- OnlineLast2Days
- OnlineLast3Days
- OnlineLast4Days
- OnlineLast5Days
- OnlineLast6Days
- OnlineLast7Days
- OnlineToday
- ReAssignToInventoryPending
- ReAssignToMerchantInventoryPending
- ReAssignToStorePending
- SwitchedOff
type: string
wifiIp:
description: The terminal's IP address in your Wi-Fi network.
type: string
wifiMac:
description: The terminal's MAC address in your Wi-Fi network.
type: string
required:
- companyAccount
- terminal
type: object
GetTerminalsUnderAccountRequest:
properties:
companyAccount:
description: >-
Your company account. If you only specify this parameter, the
response includes all terminals at all account levels.
type: string
merchantAccount:
description: >-
The merchant account. This is required if you are retrieving the
terminals assigned to a store.If you don't specify a `store` the
response includes the terminals assigned to the specified merchant
account and the terminals assigned to the stores under this merchant
account.
type: string
store:
description: >-
The store code of the store. With this parameter, the response only
includes the terminals assigned to the specified store.
type: string
required:
- companyAccount
type: object
GetTerminalsUnderAccountResponse:
properties:
companyAccount:
description: Your company account.
type: string
inventoryTerminals:
description: >-
Array that returns a list of all terminals that are in the inventory
of the company account.
items:
type: string
type: array
merchantAccounts:
description: >-
Array that returns a list of all merchant accounts belonging to the
company account.
items:
$ref: '#/components/schemas/MerchantAccount'
type: array
required:
- companyAccount
type: object
MerchantAccount:
properties:
inStoreTerminals:
description: >-
List of terminals assigned to this merchant account as in-store
terminals. This means that the terminal is ready to be boarded, or
is already boarded.
items:
type: string
type: array
inventoryTerminals:
description: >-
List of terminals assigned to the inventory of this merchant
account.
items:
type: string
type: array
merchantAccount:
description: The merchant account.
type: string
stores:
description: Array of stores under this merchant account.
items:
$ref: '#/components/schemas/Store'
type: array
required:
- merchantAccount
type: object
ServiceError:
properties:
errorCode:
description: The error code mapped to the error message.
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/pos-terminal-openapi-original.yml