Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Assign terminals with Terminal Management API

Use API calls to get an overview of your payment terminals and to assign terminals to your stores.

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. That is what we describe on this page.

The advantage of using the Terminal Management API, is that API calls enable you to automate assigning terminals. This is especially useful if you are managing a large number of terminals.

With the API you can:

Based on this information, you can then:

Before you begin

To make these API calls and interpret the responses, you need to be aware that the API shows terminals as having 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 can't be boarded. A terminal that's in store is either ready for boarding, or is already boarded.

Terminals at company account level are always inventory terminals, and terminals at store level are always in-store terminals. If the merchant account has stores underneath, it 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 your company account as inventory terminals. 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.

Set up the webservice user

To be able to use the Terminal Management API, make sure your Admin user creates a web service user that has the following permissions:

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

You need to specify the API key for this web service user in the header of your Terminal Management API requests.

Find the account or store that a terminal is assigned to

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

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

    • Your API key in the request header.
    • terminal: The unique terminal ID in the format [Device model]-[Serial number], for example V400m-324689776
    /findTerminal request
    {
        "terminal" : "M400-114400123"
    }

    The response shows:

    • companyAccount: The company account of the terminal.
    • merchantAccount: The merchant account of the terminal, 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 is assigned to a merchant account.

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

Find all terminals for an account

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

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

    • Your API key in the request header.
    • companyAccount: Your company account name. If you only specify this parameter, you get an overview of the company account, merchant accounts, and stores, and their terminals.
    • merchantAccount: Your merchant account name (optional). If you specify this parameter, the overview only includes the terminals at the company account level and the terminals of the specified merchant account and the associated stores.
    /getTerminalsUnderAccount request
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT"
    }

    The response shows:

    • The account level that a terminal is at: Company account, merchant account, or store.
    • 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 in the in-store state at the merchant account 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.

    /getTerminalsUnderAccount 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. Make sure 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 POST request to the /getTerminalsUnderAccount endpoint as described above.
  2. Make a POST request to the /assignTerminals endpoint, specifying:

    • Your API key in the request header.
    • companyAccount: Your company account name. To assign terminals back to the company inventory, specify only this parameter and the terminals parameter.
    • merchantAccount: Your merchant account name.
    • merchantInventory: To assign the terminals to the merchant account, specify this parameter with a value of true or false and don't provide the store parameter.
      • The value true assigns the terminals to the merchant account inventory.
      • The value false changes the terminals to in store terminals assigned to the merchant account.
    • store: To assign terminals to a store, specify the store code here, and do not provide the merchantInventory parameter.
    • terminals: An array of the terminals you want to assign. Provide unique terminal IDs in the format [Device model]-[Serial number].
    /assignTerminals to company inventory
    
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT",
        "terminals" : ["V400m-324689776","P400Plus-329127412"]
    }
    /assignTerminals to merchant inventory
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT",
        "merchantAccount" : "YOUR_MERCHANT_ACCOUNT_EU",
        "merchantInventory" : true,
        "terminals" : ["V400m-324689776","P400Plus-329127412"]
    }
    /assignTerminals to merchant account as in-store terminals
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT",
        "merchantAccount" : "YOUR_MERCHANT_ACCOUNT_US",
        "merchantInventory" : false,
        "terminals" : ["V400m-324689776","P400Plus-329127412"]
    }
    /assignTerminals to a store
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT",
        "merchantAccount" : "YOUR_MERCHANT_ACCOUNT_EU",
        "store" : "YOUR_STORE_CODE",
        "terminals" : ["V400m-324689776","P400Plus-329127412"]
    }

    The response shows:

    • Done: Indicates the terminal has been assigned.
    • AssignmentScheduled: Indicates 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.
    Response
    {
        "results": {
            "V400m-324689776": "ActionScheduled",
            "P400Plus-329127412": "Done"
        }
    }
  3. To verify, optionally repeat the /getTerminalsUnderAccount request.

See also