Managing terminals

As a platform, you can onboard and manage multiple terminals at the same time, within different profiles. This page covers how you can purchase and activate terminals, how platform-managed devices work, and how to discover and store terminal information in your platform.

Purchasing and activating terminals

Before a terminal can be used, it must be assigned to a connected account and paired to a profile. How this works depends on whether you are setting up a hardware terminal or a Mollie Tap terminal.

Hardware terminals

There are three options for getting hardware terminals:

1. Purchase for your account — you can purchase devices for your account directly from Mollie via the Web App. Mollie ships the device directly to your business.
2. Purchase on behalf of the connected account — you can opt to purchase and ship the device directly to the connected account. Mollie handles shipping, but charges the platform for the terminal.
3. Purchase and re-assign — you can purchase the device from Mollie to receive it yourself and later re-assign to a connected account via the Partner Dashboard.

In all cases, the terminal's activation status is managed by Mollie when the device is shipped. No API action is needed.

The key difference between these options is who handles shipping:

• You handle shipping — purchase devices in bulk from Mollie, then re-assign and ship them to connected accounts at a later stage. This is practical if you ship terminals alongside other hardware, such as a kiosk.
• Mollie handles shipping — purchase the device on behalf of your connected account or let the customer purchase the device(s) themselves. This is practical if you want Mollie to handle shipping and delivery.

Viewing your terminals

To view all connected terminals and their details:

1. In your Mollie Web App, go to In-person payments.
2. Select the terminal you want to inspect.
3. Click on Terminal information at the top of your screen.

The detail page shows:

• Status - is your terminal activated or not
• Network status - is your terminal connected to the internet
• Battery - the percentage of battery reported by your terminal
• Last known location - the location of your terminal (based on its IP address)
• PIN code - the PIN code used to access the device (view by clicking the eye icon)

And some additional details listed:

• Terminal name - the label you've assigned to the device
• Model - the hardware mode
• Serial number - the physical device serial number
• Profile - profile the terminal is linked to
• Terminal ID - the unique identifier for the terminal

To see all transactions processed by a specific terminal, select a terminal to open the page showing you the transaction overview for that terminal.

Renaming terminals

Giving each terminal a descriptive name makes it easier to identify transactions by location or till. To rename a terminal:

• Select the terminal you want to rename.
• Go to Terminal information > click Rename > enter the new name and save.

Use names that reflect where the terminal is physically located, for example "Checkout 1" or "Amsterdam Store Front", this makes it easier to filter transactions in the future.

Terminal statuses

Every terminal can be in one of three statuses:

Retrieve terminals using API

Once a terminal is active in Mollie, your platform needs to add it and allow the connected accounts to onboard the terminal(s). A typical flow looks like this:

1. Fetch available terminals — call the List terminals endpoint to retrieve all connected account's terminals.
2. List terminals to the connected account — display the available terminals in your UI, so the connected account can select which terminal to use.
3. Onboard the terminal in your platform — let the connected account associate the terminal with a relevant entity in your software (e.g., a cash register, workstation or location). Alternatively, prompt users to select which terminal should be used as the default terminal for processing payments.

Example get a single terminal:

curl https://api.mollie.com/v2/terminals/term_7MgL4wea46qkRcoTZjWEH \
  -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"

Example response:

{
  "resource": "terminal",
  "id": "term_7MgL4wea46qkRcoTZjWEH",
  "mode": "live",
  "status": "active",
  "brand": "PAX",
  "model": "A920",
  "serialNumber": "1234567890",
  "currency": "EUR",
  "description": "Terminal #12345",
  "profileId": "pfl_QkEhN94Ba",
  "createdAt": "2022-02-12T11:58:35+00:00",
  "updatedAt": "2022-02-12T11:58:35+00:00",
  "_links": {
    "self": {
      "href": "...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "...",
      "type": "text/html"
    }
  }
}

Managed devices

When your platform is involved in purchasing or activating a terminal, that device automatically becomes a platform-managed device. No explicit API action is required.

For hardware terminals, the device becomes managed when you purchase it on behalf of the connected account or re-assign to a different profile after purchasing.

For Tap terminals, the device becomes managed when the terminal is paired using a QR code generated via the API with the connected account's OAuth token.

Benefits of managed devices

• Monetization — using resell pricing can monetize terminal-initiated payments created locally on the device in addition to any monthly terminal fees.
• Exclusivity — managed devices cannot be assigned or used outside of your platform's ecosystem.

Authentication considerations

OAuth access token — recommended

When authenticating with an OAuth access token, the List terminals endpoint returns all terminals across all profiles belonging to the connected account. This is the recommended approach, especially for connected accounts with multiple profiles (common if the merchant has separate profiles for different locations).

API key

If you are authenticating with an API key, the key is bound to a specific profile. This means:

• The List terminals endpoint only returns terminals registered to the profile associated with that API key
• You must use an API key from the same profile the terminal is registered to when creating payments
• If a connected account has multiple terminals registered to different profiles, you need to use a separate API key for each profile

Hence why OAuth is strongly recommended for platforms managing terminals across multiple profiles.