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.

Terminal statuses

Every terminal can be in one of three statuses:

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.

Tap terminals

For Tap terminals or devices running the Tap app, the terminal must be paired using a QR code. You can generate a pairing code via the API using the connected account's OAuth token. This allows platforms to embed the activation journey in their own platform. See Authorizing Mollie users within your app for details.

Alternatively, the connected account can complete the pairing flow in their Mollie Web App.

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.

Discovering and storing terminals

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 terminal 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"
    }
  }
}

Multi-profile management

Larger connected accounts may operate multiple profiles, each with multiple terminals assigned to them. Your platform should keep track of which terminals belong to which profiles. You can use separate payment profiles to group terminals by store or location to make it easier.

Terminal re-assignment

Connected accounts can re-assign a terminal to a different profile via the Mollie Web App, and platforms can do so via the Partner Dashboard.

To handle this, consider building a flow that allows connected accounts to refresh or re-sync their terminal assignments within your platform.

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.