Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Terminal Management API

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

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 calls enable you to automate processes like assigning terminals. This is especially useful if you are managing a large number of terminals.

With the Terminal Management API you can:

On this page, we provide links to our API Explorer, for example /getTerminalDetails, where you can try out the request and see the full response details.

Inventory and in-store terminals

To make Terminal Management API calls 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 can't be boarded. A terminal that's 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, 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.

Before you begin

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 level of a terminal

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.
    • The request body with:

      Parameter Required Description
      terminal -white_check_mark- The unique ID of the terminal in the format [Device model]-[Serial number].
    /findTerminal request
    {
        "terminal" : "P400Plus-114400124"
    }

    The response shows 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.

    /findTerminal response: In-store terminal assigned to a merchant account
    {
        "companyAccount": "YOUR_COMPANY_ACCOUNT",
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT_US",
        "merchantInventory": false,
        "terminal": "M400-328521222"
    }
    /findTerminal response: Terminal assigned to a store
    {
        "companyAccount": "YOUR_COMPANY_ACCOUNT",
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT_EU",
        "merchantInventory": false,
        "store": "Store_EU_001",
        "terminal": "P400Plus-114400124"
    }

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 all these data using the Terminal Management API:

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

    • Your API key in the request header.
    • The request body with:

      Parameter Required Description
      terminal -white_check_mark- The unique ID of the terminal in the format [Device model]-[Serial number].
    /getTerminalDetails request
    {
        "terminal" : "P400Plus-114400124"
    }

    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 it's 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.

    /getTerminalDetails response
    {
        "companyAccount": "YOUR_COMPANY_ACCOUNT",
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT_EU",
        "merchantInventory": false,
        "store": "STORE_EU_001",
        "terminal": "P400Plus-114400124",
        "deviceModel": "P400Plus",
        "serialNumber": "114-400-124",
        "permanentTerminalId": "60299843",
        "terminalStatus": "OnlineToday",
        "firmwareVersion": "Verifone_VOS 1.50.7",
        "country": "NETHERLANDS",
        "storeDetails": {
            "store": "Store_EU_001",
            "description": "EU store Amsterdam",
            "address": {
                "city": "Amsterdam",
                "countryCode": "NL",
                "postalCode": "1234",
                "streetAddress": "The Street"
            }
        },
        "lastTransactionDateTime": "2020-05-28T08:41:16+02:00",
        "lastActivityDateTime": "2020-05-28T12:35:06+02:00",
        "wifiMac": "10:98:c3:68:a3:d4",
        "wifiIp": "192.0.2.1",
        "dhcpEnabled": false
    }

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:

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

    • Your API key in the request header.
    • The request body with:

      Parameter Required Description
      companyAccount -white_check_mark- 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 don't 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.
    /getTerminalsUnderAccount request
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT"
    }

    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.
    /getTerminalsUnderAccount response
    {
        "companyAccount": "YOUR_COMPANY_ACCOUNT",
        "inventoryTerminals": [
            "E2585-111355123",
            "E2585-111915124"
        ],
        "merchantAccounts": [
            {
                "merchantAccount": "YOUR_MERCHANT_ACCOUNT_EU",
                "inventoryTerminals": [
                    "M400-134400194",
                    "V400m-111400143",
                    "P400Plus-111212878"
                ],
                "inStoreTerminals": [
                    "E285-111355124",
                    "V400m-111400140"
                ],
                "stores": [
                    {
                        "store": "Store_EU_001",
                        "inStoreTerminals": [
                            "P400Plus-114400124"
                        ]
                    }
                ]
            },
            {
                "merchantAccount": "YOUR_MERCHANT_ACCOUNT_US",
                "inStoreTerminals": [
                    "VX820-367008385",
                    "M400-328521222"
                ]
            }
        ]
    }

Get all stores under an account

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

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

    • Your API key in the request header.
    • The request body with:

      Parameter Required Description
      companyAccount -white_check_mark- 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.
    /getStoresUnderAccount request
    {
        "companyAccount" : "YOUR_COMPANY_ACCOUNT"
    }

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

    • status: The status of the store can be:

      • 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.
    /getStoresUnderAccount response
    {
        "stores": [
            {
                "store": "Store_EU_001",
                "description": "EU store Amsterdam",
                "address": {
                    "city": "Amsterdam",
                    "countryCode": "NL",
                    "postalCode": "1234",
                    "streetAddress": "The Street"
                },
                "status": "Active",
                "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT_EU"
            },
            {
                "store": "Store_EU_002",
                "description": "EU store Paris",
                "address": {
                    "city": "Paris",
                    "countryCode": "FR",
                    "postalCode": "1234",
                    "streetAddress": "La Place"
                },
                "status": "Inactive",
                "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT_EU"
            }
        ]
    }

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 request to the /assignTerminals endpoint, specifying:

    • Your API key in the request header.
    • The request body with the following parameters, depending on what you want to do:

      Parameter Required Description
      companyAccount -white_check_mark- The name of the company account.
      merchantAccount The name of the merchant account.
      merchantInventory true or false
      store The store code.
      terminals -white_check_mark- 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 , and set merchantInventory to false.
    /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 a result for each terminal:

    • Done: The terminal has been assigned.
    • AssignmentScheduled: The terminal will be assigned asynchronously. You can set up receiving Terminal Assignment Complete notifications to be informed when the assignment is done.
    • RemoveConfigScheduled: The terminal was previously boarded. Wait for the terminal to synchronize with the Adyen platform.
    Response
    {
        "results": {
            "V400m-324689776": "ActionScheduled",
            "P400Plus-329127412": "Done"
        }
    }
  3. To verify, optionally repeat the /getTerminalsUnderAccount request.

Terminal Assignment Complete notifications

In some cases, we can't 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 notifications, follow the general instructions to set up notifications:

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

After you set up the notification type, you will receive Terminal Assignment Complete notifications 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": "YOUR_MERCHANT_ACCOUNT",
  "eventDate": "2020-06-03 22:42:13.840 CEST",
  "pspReference": "NO_PSP_REF_1591216933840470",
  "uniqueTerminalId": "V400m-324689776"
}

See also