Assign terminals

To make terminals ready for boarding, you need to assign them to a store or, depending on your account setup, to a merchant account as in-store terminals. You can assign your terminals manually in your Customer Area, but Management API enables you to automate these processes.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Inventory and in-store terminals

When assigning terminals, you need to be aware that terminals have both:

• A level in your account setup: company account, merchant account, or store. Depending on your account setup, the merchant account may represent a store.
• A state: inventory or in store. A terminal in the inventory cannot process transactions. A terminal that is in store is either ready for boarding, or is already boarded.

Terminals at the company account level are always inventory terminals, and terminals at the store level are always in-store terminals. If the merchant account has stores underneath, the merchant account can only have inventory terminals. A merchant account that represents a store can have both inventory terminals and in-store terminals.

Therefore, you can assign terminals to:

• A company account: terminals cannot process transactions.
• A merchant account inventory: terminals cannot process transactions.
• A merchant account directly: terminals can process transactions.
• A store: terminals can process transactions.

Get a list of stores

You can make a GET /merchants/{merchantId}/stores request to retrieve the list of stores under your merchant account. You can then reassign your terminals to the specific storeId.

To make this request to Management API, you need to have an API credential with an API key and the following roles:

• Management API—Stores read
• Management API—Stores read and write

To retrieve the list of stores:

1. Make a GET /merchants/{merchantId}/stores request, specifying:

   • As a path parameter:

   Parameters	Required	Description
   merchantId		The unique identifier of the merchant account.

   • As query parameters:

   Parameters	Description
   reference	The reference of the store.
   pageSize	The number of items to have on a page, maximum 100. The default is 10 items on a page.
   pageNumber	The number of the page to fetch.

2. The response returns a paginated list of stores for the specified merchant account. The data object contains the following details for every store:

3. From the response, save the storeId and make a assign terminals request to reassign the terminal to that store.

Get terminal details

To get the list of terminals for your API credential, you can use the GET /terminals request. The response also returns the details of each terminal, like the id, the account level to which it is assigned, the IP address, and the software version of the terminal.
You can then use these details to reassign a specific terminal to another level in your account structure.

To make this request to Management API, you need to have an API credential with an API key and the following roles:

• Management API — Terminal actions read

To retrieve the list of terminals and their details:

1. Make a GET /terminals request.

2. The response returns a paginated list of terminals for the specified API credential. The data object contains the following details for every terminal:

   Parameters	Description
   assignment	An object with: companyId: the unique identifier of the company account to which terminal is assigned. merchantId: the unique identifier of the merchant account to which terminal is assigned. reassignmentTarget: indicates where the terminal is in the process of being reassigned to. status: the status of the reassignment. storeId: the unique identifier of the store to which terminal is assigned.
   connectivity	Information about bluetooth, cellular, ethernet, and Wi-Fi connectivity for the terminal.
   firmwareVersion	The software release currently in use on the terminal.
   id	The unique identifier of the terminal.
   lastActivityAt	Date and time of the last activity on the terminal. Not included when the last activity was more than 14 days ago.
   lastTransactionAt	Date and time of the last transaction on the terminal. Not included when the last transaction was more than 14 days ago.
   model	The model name of the terminal.
   serialNumber	The serial number of the terminal.

3. From the response, save the terminalId and make a assign terminals request to reassign the terminal to a different account level.

Assign terminals

To make a terminal ready to accept payments, you need to assign it to a store or a merchant account representing a store, and then board the terminal.

To make the POST /terminals/{terminalId}/reassign request, you need to have an API credential with an API key and the following roles:

• Management API—Assign Terminal

1. Prepare for assigning terminals:

   • Make sure that you have terminalId of the terminal that you want to reassign. To get the ID, make a GET /terminals request.
   • Optionally, make a GET /merchants/{merchantId}/stores request to retrieve an overview of your stores and their details.

2. Make a POST /terminals/{terminalId}/reassign request, specifying:

   • As a path parameter:

   Parameter	Required	Description
   terminalId		The unique identifier of the payment terminal in the format [Device model]-[Serial number].

   • As request parameters:

   Parameter	Description
   companyId	The unique identifier of the company account to which the terminal is reassigned.
   merchantId	The unique identifier of the merchant account to which the terminal is reassigned. When reassigning terminals to a merchant account, you must specify the inventory field.
   inventory	Indicates if the terminal is reassigned to the inventory of the merchant account. If true, the terminal is in the inventory of the merchant account and cannot process transactions. If false, the terminal is reassigned directly to the merchant account and can process transactions.
   storeId	The unique identifier of the store to which the terminal is reassigned.

3. Because the request is processed asynchronously, the response returns HTTP status code 200/OK.

   When the terminal is online, it downloads and applies the new configuration. The terminal is then ready for boarding.

Terminal assignment complete webhooks

In some cases, it is not possible to assign a terminal synchronously and we schedule the assignment for later. To let you know when the assignment is completed, we send you a Terminal assignment complete webhook. This is sent as an HTTP callback to your server.

To set up receiving Terminal assignment complete webhooks, follow the general instructions to set up webhooks:

1. Expose an endpoint on your server where you want to receive the webhooks.
2. Set up the webhooks in your Customer Area as described, but select Terminal assignment complete (not Standard webhook) as the webhook type you want to add.
3. Make sure that you accept webhooks correctly.
4. Test and go live.

After you set up the webhook type, you will receive Terminal assignment complete webhook with:

• The account (assignedToAccount) or store (assignedToStore) that the terminal is assigned to.
• The date and time when the assignment was carried out.
• The ID of the terminal involved.

{
  "assignedToAccount": "ADYEN_MERCHANT_ACCOUNT",
  "assignedToStore": "YOUR_STORE",
  "eventDate": "2020-06-03 22:42:13.840 CEST",
  "pspReference": "NO_PSP_REF_1591216933840470",
  "uniqueTerminalId": "V400m-324689776"
}

See also