Assign terminals

To enable taking payments on a payment terminal, the first step is to reassign the terminal from its initial account level and status to a level and status that allows boarding. Then the terminal needs to be boarded.

You can reassign your terminals manually in your Customer Area, but Management API enables you to automate the reassignment.

Requirements

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

Account level and status of terminals

When (re)assigning terminals, you need to be aware of the following:

• A terminal is always assigned to a level in your account setup: Company account, merchant account, or store. Note that some account setups do not have a store level and instead use merchant accounts to represent stores.

• A terminal has a status:

  • inventory: The terminal is in inventory and cannot process transactions.
  • reassignmentInProgress: A request to change the assignment of the terminal is being processed.
  • deployed: The terminal has been reassigned and is ready for boarding.
  • boarded: The terminal is boarded to a store, or to a merchant account representing a store, and can process transactions.

A new terminal is pre-assigned to the company or merchant account that the terminal was ordered for, and has the inventory status. To be able to process transactions, you reassign the terminal to a store, and then board the terminal. Or in an account setup that uses merchant accounts to represent stores, your reassignment to a merchant account needs to explicitly take the terminal out of the inventory status, and then you board the terminal.

Get a list of stores

To reassign terminals to a specific store, you need to know the ID of the store. To find the store ID:

1. Make a GET /merchants/{merchantId}/stores request, specifying path and query parameters:

   Path parameter	Required	Description
   merchantId		The unique identifier of the merchant account.

   Query parameter	Required	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.

   The response returns a paginated list of stores for the specified merchant account.

2. From the response, save the storeId of the store that you want to assign terminals to. You need to specify that ID when you assign terminals to that store.

Get terminal details

To reassign a terminal, you need to know the ID of the terminal. To find the terminal ID and other details like the account level to which the terminal is currently assigned:

1. Make a GET /terminals request.

   The response returns a paginated list of terminals that your API credential has access to.

2. From the response, save the id of the terminal that you want to assign to a specific account level. The response returns the following details for each terminal:

   Response parameter	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 the 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	The date and time of the last activity on the terminal. Not included when the last activity was more than 14 days ago.
   lastTransactionAt	The 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.

Reassign terminals

To enable taking payments on a payment terminal, you need to reassign the terminal from its initial account level and status to a level and status that allows boarding. Then you need to board the terminal.

1. Prepare for assigning terminals:

   • Make sure you know the ID of the terminal that you want to reassign. See Get terminal details.
   • If you are going to reassign the terminal to a store, make sure you know the ID of the store. See Get a list of stores.

2. Make a POST /terminals/{terminalId}/reassign request, specifying path and request body parameters:

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

   Body parameter	Required	Description
   companyId		The unique identifier of the company account.
   merchantId		The unique identifier of the merchant account. When reassigning terminals to a merchant account, you must also specify the inventory field.
   inventory		Required when reassigning a terminal to a merchant account. If true, the terminal is assigned to the inventory of the merchant account and cannot process transactions. If false, the terminal is taken out of the inventory and can be boarded.
   storeId		The unique identifier of the store.

3. Check that the response returns HTTP status code 200/OK. The request is processed asynchronously.

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 reassign a terminal immediately, and we schedule the assignment for later. To let you know when the reassignment is completed, we send you a terminalAssignment.completed webhook message. This is sent as an HTTP callback to your server.

To set up receiving these webhook messages, follow the general instructions to set up webhooks but select Terminal assignment complete (not Standard) as the webhook type you want to add.

After you set up the webhook type, you will receive terminalAssignment.completed webhook messages 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