Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Assign terminals in bulk

Use Terminal Management API calls to assign payment terminals to your stores.

To make a terminal ready to accept payments, you need to assign it to a store and then board the physical terminal. There are two ways to assign terminals:

  • Using your Customer Area. How to do that, is described under Board the terminal.
  • Using the Terminal Management API. This is what we describe here on this page.

The advantage of using the Terminal Management API over the Customer Area, is that API calls enable you to automate assigning terminals and retrieving an overview of terminal assignments. This API lets you:

But before you start, you need to be aware of the following:

  • Terminals can be in the inventory or in store:

    • When a terminal is in the inventory of your company or merchant account, it has been assigned to that entity but it can't be boarded.
    • When a terminal is in store, it has been assigned to the entity and is either ready for boarding or has been boarded already.

  • At the company account level, terminals are always in the inventory. At the store level, terminals are always in store.
  • Some companies have an account structure that has one or more merchant accounts with stores underneath. Other companies have an account structure with many merchant accounts that represent stores. To accommodate that last structure, merchant accounts can have terminals in store.
  • If a terminal has been boarded already and you assign it to a different store, you'll need to board the terminal again.

Set up the webservice user

To be able to use the Terminal Management API, make sure your webservice user has the following permissions:

  • Access to the company account.
  • The POS Terminal Management API role.

Terminal Management API endpoints

These are the test endpoints for the Terminal Management API:

Find the entity that a terminal is assigned to

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

  1. Make a POST request to the /findTerminal endpoint, specifying:

    • terminal: The unique terminal ID in the format [Device model]-[Serial number], for example V400m-324689776.
      {
      "terminal" : "M400-114400123"
      }
  2. Receive the response. This shows:

    • companyAccount: The company account that the terminal is assigned to.
    • merchantAccount: The merchant account that the terminal is assigned to, if applicable.
    • store: The store code of the store that the terminal is assigned to, if applicable.
    • terminal: The ID of the terminal.

    The following example shows the response for a terminal that's assigned to a merchant account.

    {
        "companyAccount": "YOUR_COMPANY_ACCOUNT",
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
        "terminal": "M400-114400123"
    }

Retrieve all terminals for an account

To retrieve a list of terminals associated with an account or store and see if the terminals are in the inventory or in store:

  1. Make a POST request to the /getTerminalsUnderAccount endpoint, specifying:

    • companyAccount: Your Adyen company account. If you only use this parameter, you get a list of all terminals at company, merchant, and store level. Merchants or stores that don't have a terminal are omitted from the response.
    • merchantAccount: Optional. Your merchant account used for accepting payments. If you add this parameter, you get a list of all terminals of the specified merchant and the associated stores. Stores that don't have a terminal are omitted from the response.
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT"
    }
  2. Receive the response. This shows:

    • The level that a terminal is at.
    • Whether the terminal is in the inventory or in store:
      • inventoryTerminals: Terminals assigned to the inventory at the company or merchant account level.
      • inStoreTerminals: Terminals assigned at the merchant or store level. These terminals are either ready for boarding or already boarded.
    • The unique ID of the terminal: [Device model]-[Serial number], for example V400m-324689776.

    Any account or store that doesn't have a terminal assigned to it, is not included in the response.

    {
        "companyAccount": "YOUR_COMPANY_ACCOUNT",
        "inventoryTerminals": [
            "E2585-111355123",
            "E2585-111915124"
        ],
        "merchantAccounts": [
            {
                "merchantAccount": "YOUR_MERCHANT_ACCOUNT_EU",
                "inventoryTerminals": [
                    "M400-114400124",
                    "V400m-111400143",
                    "P400Plus-111212878"
                ],
                "inStoreTerminals": [
                    "E285-111355124",
                    "V400m-111400140"
                ],
                "stores": [
                    {
                        "store": "YOUR_STORE_CODE",
                        "inStoreTerminals": [
                            "M400-114400123"
                        ]
                    }
                ]
            },
            {
                "merchantAccount": "YOUR_MERCHANT_ACCOUNT_US",
                "inStoreTerminals": [
                "VX820-367008385",
                "VX690-328521222"
                ]
            }
        ]
    }

Assign terminals

To assign terminals using the Terminal Management API:

  1. To check the available terminals, make a POST request to the /getTerminalsUnderAccount endpoint as described above.
  2. Make a POST request to the /assignTerminals endpoint, specifying:

    • companyAccount: Your Adyen company account.
    • merchantAccount: Your merchant account used for accepting payments.
    • merchantInventory: CONDITIONAL Required if you are assigning the terminals to the merchant account and not to a store. Do not include if you are assigning the terminals to a store.
      • The value true assigns the terminals to the inventory of the merchant account. This means the terminals can't be boarded.
      • The value false changes the terminals to in store terminals assigned to the merchant account. This means the terminals can be boarded and can process payments over that merchant account.
    • store: The store code of the store that you want to assign the terminals to.
    • terminals: An array of the terminals you want to assign. Use the unique terminal IDs returned in the /getTerminalsUnderAccount response.
      In most cases you'll assign one or more inventoryTerminals, but you could also re-assign a terminal that's already assigned to another entity.
    
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT",
        "terminals" : ["V400m-324689776","P400Plus-329127412"]
    }
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT",
        "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
        "merchantInventory" : true,
        "terminals" : ["V400m-324689776","P400Plus-329127412"]
    }
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT",
        "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
        "store" : "YOUR_STORE_CODE",
        "terminals" : ["V400m-324689776","P400Plus-329127412"]
    }
  3. Receive the response:

    • Done indicates the listed terminal has been assigned.
    • AssignmentScheduled means the terminal was previously boarded. To complete the reassignment, you need to remove the terminal configuration, or wait until the terminal synchronizes with the Adyen platform.
    {
        "results": {
            "V400m-324689776": "ActionScheduled",
            "P400Plus-329127412": "Done"
        }
    }
  4. To check, optionally repeat the /getTerminalsUnderAccount request.

See also