Classic assign terminals

The Terminal Management API provides endpoints for retrieving information about your payment terminals and assigning them. You can do the same using your Customer Area, but API requests enable you to automate these processes.

With the Terminal Management API you can:

• Obtain information about a specific terminal. You can get either all available details or only the account level that the terminal belongs to.

• Prepare for assigning terminals by:

  • Discovering the terminals that you have.

  • Discovering the stores that you could assign terminals to.

• Assign terminals to a store (or merchant account representing a store) so they can be boarded, or reassign terminals back to the inventory or to another store or account.

Inventory and in-store terminals

To make Terminal Management API requests and interpret the responses, 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. An inventory terminal cannot be boarded. 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.

When we ship your terminals to you, we add them to the inventory of the account that you ordered the terminals from. To make terminals ready for boarding, you assign them to a store or, depending on your account setup, you assign them to a merchant account as in-store terminals.

Authentication, versioning, and endpoints

To authenticate your requests to POS Terminal Management API, you need to have an API credential with an API key and the following role:

• POS Terminal Management API role

There are two endpoints:

• Test: https://postfmapi-test.adyen.com/postfmapi/terminal/v1/
• Live: https://postfmapi-live.adyen.com/postfmapi/terminal/v1/

Versioning is handled as part of the endpoint URL. For example, to retrieve terminal information using version 1 of the Terminal Management API, use:

• Test: https://postfmapi-test.adyen.com/postfmapi/terminal/v1/getTerminalDetails

When using versioned endpoints, Boolean response values are returned in string format: "true" or "false".
If you omit the version from the endpoint URL, Boolean response values are returned like this: true or false.

Find the account level of a terminal

To retrieve the company account, merchant account, or store that your payment terminal is assigned to:

1. Make a POST /findTerminal request, specifying:

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

2. In the response shows, check where the terminal is assigned to. Note the following:

   • If the companyAccount is the only account level shown, the terminal is in the inventory of the company account.
   • If merchantInventory is false, the terminal is either assigned to the merchant account as an in-store terminal, or assigned to the store that is specified in the response.

   The /getTerminalDetails request gives the same information plus many more details about the terminal.

   Here are some response examples.

Get the details of a terminal

There is a lot of information available about each terminal. For example, the account or store that a terminal belongs to, the date and time of the last transaction, the IP address, and the firmware version of the terminal.

To retrieve terminal data using the Terminal Management API:

1. Make a POST /getTerminalDetails request, specifying:

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

2. In the response, note the following:

   • If the companyAccount is the only account level shown, the terminal is in the inventory of the company account.

   • merchantAccount: if the response doesn't contain a store, the terminal is assigned to this merchant account. To determine whether the terminal is an inventory terminal or an in-store terminal, make a /getTerminalsUnderAccount request.

   • terminalStatus:

     • 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.

   • lastTransactionDateTime: this property is not included when the last transaction was more than 14 days ago.

   • lastActivityDateTime: this property is not included when the last activity was more than 14 days ago.

   The following example shows the response for a terminal that is assigned to a store.

Get all terminals under an account

To retrieve an overview of terminals belonging to an account or store and see if these are inventory or in-store terminals:

1. Make a POST /getTerminalsUnderAccount request, specifying:

   Parameter	Required	Description
   companyAccount		The name of the company account. If you only specify this parameter, the response includes all terminals at all account levels.
   merchantAccount		The name of a merchant account. Required if you want to get the terminals for a specific store. If you do not specify a store the response includes the terminals belonging to the specified merchant account and the terminals belonging to all stores under this merchant account.
   store		With this parameter, the response only includes the terminals of the specified store.

2. In the response, note the following:

   • inventoryTerminals under companyAccount: these are the terminals in the inventory of the company account. They are shown only when the company account was the only request parameter.

   • merchantAccounts: an array with the merchant accounts under the company account. Merchant accounts without terminals are not included. For each merchant account the terminals are grouped into:

     • inventoryTerminals: terminals assigned to the inventory of the merchant account.

     • inStoreTerminals: terminals assigned to the merchant account as in-store terminals.

     Terminals at the merchant account level are not shown if your request specified a store.

   • stores: an array with the stores under the specified merchant account. Stores without terminals are not included.

Get all stores under an account

To retrieve an overview of stores under a company account or merchant account:

1. Make a POST /getStoresUnderAccount request, specifying:

   Parameter	Required	Description
   companyAccount		The name of the company account. If you only specify this parameter, the response includes all stores under merchant accounts belonging to the company account.
   merchantAccount		The name of a merchant account. With this parameter, the response only includes the stores under the specified merchant account.

2. The response consists of a stores array with store details. Note the following:

   • status: the status of the store. Possible values:

     • PreActive: the store has been created, but not yet activated.
     • Active: the store has been activated. This means you can process payments over the merchant account or store.
     • Inactive: the store is currently not active.
     • InactiveWithModifications: the store is currently not active, but payment modifications such as refunds are still allowed.

     • Closed: the store has been closed.

   • merchantAccountCode: the merchant account that the store belongs to.

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 physical terminal. You can assign terminals using your Customer Area, but you can also use the Terminal Management API.

To assign terminals using the Terminal Management API:

1. Prepare for assigning terminals:

   • Make sure that you have the unique terminal IDs in the format [Device model]-[Serial number] of the terminals that you want to assign. To get these IDs, you can make a /getTerminalsUnderAccount request.

   • Optionally make a /getStoresUnderAccount request to retrieve an overview of your stores and their store codes.

2. Make a POST /assignTerminals request, specifying a request body with the following parameters,
   depending on what you want to do:

   Parameter	Required	Description
   companyAccount		The name of the company account.
   merchantAccount		The name of the merchant account.
   merchantInventory		true or false
   store		The store code.
   terminals		An array of the terminals you want to assign. Provide unique terminal IDs in the format [Device model]-[Serial number].

   • To return terminals to the company inventory, specify the companyAccount and the terminals.

   • To assign terminals to a merchant account inventory, specify the companyAccount, merchantAccount, and terminals, and set merchantInventory to true.

   • To assign terminals to a merchant account as in-store terminals, specify the companyAccount, merchantAccount, and terminals, and set merchantInventory to false.

   • To assign terminals to a store, specify the companyAccount, merchantAccount, store, and terminals.

3. In the response, note the result for each terminal:

   • Done: the terminal has been assigned.
   • AssignmentScheduled: the terminal will be assigned asynchronously. You get this result when assigning multiple terminals that were not previously boarded. You can set up receiving Terminal assignment complete webhooks to be informed when the assignment is done.
   • RemoveConfigScheduled: the terminal was previously boarded. Wait for the terminal to synchronize with the Adyen platform.

4. To verify, optionally repeat the /getTerminalsUnderAccount request.

Terminal assignment complete webhooks

In some cases, we cannot assign a terminal synchronously and we schedule the assignment for later. The /assignTerminals response then returns an AssignmentScheduled result for that terminal. To let you know when the assignment is completed, we send you a Terminal assignment complete notification. This is sent as an HTTP callback (webhook) 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 notification (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",
  "eventDate": "2020-06-03 22:42:13.840 CEST",
  "pspReference": "NO_PSP_REF_1591216933840470",
  "uniqueTerminalId": "V400m-324689776"
}

See also