---
updatedAt: 2026-08-25T15:04:33.000Z
agentTools:
  projectIndex: https://docs.mollie.com/llms.txt
---

# Manage merchants

Once your merchants are onboarded and start accepting payments, your platform needs to stay up-to-date about their status. This page covers how to monitor merchant balances and capabilities programmatically and how to suspend a connection if needed.

## Checking merchant balances

You can retrieve balance information for any connected organization using their [OAuth](https://docs.mollie.com/reference/oauth-api) access token. This lets you check balance data from within your own platform, which might be useful for building financial dashboards, triggering payout requests or notifying your merchants on how much funds they have available.

To list all balances for a connected account:

```http
GET https://api.mollie.com/v2/balances
Authorization: Bearer <access_token_of_connected_customer>
```

To retrieve the primary balance directly:

```http
GET https://api.mollie.com/v2/balances/primary
Authorization: Bearer <access_token_of_connected_customer>
```

Each balance object includes:

| Field             | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `currency`        | The currency of that balance                           |
| `availableAmount` | Funds available for immediate use or payout            |
| `pendingAmount`   | Funds awaiting settlement (e.g., from recent payments) |

For the full reference and response schema, see the <Anchor target="_blank" href="https://docs.mollie.com/reference/balances-api">Balances API</Anchor>.

## Monitoring capabilities

Mollie reviews connected accounts on their initial onboarding and then during periodic compliance reviews. A previously active account can temporarily have its payment or settlement capabilities restricted during a review.

Use the [Capabilities API](https://docs.mollie.com/reference/list-capabilities) with the connected merchant's access token to check their current status:

```http
GET https://api.mollie.com/v2/capabilities
Authorization: Bearer <access_token_of_connected_customer>
```

Connect exposes two capabilities at the organization level: `payments` and `settlements`. Each can have a `status` of `unrequested`, `pending`, `enabled` or `disabled`. <br />A merchant can have `payments` enabled while their `settlements` is still `pending`, so check each capability separately rather than treating onboarding as one.&#x20;

| Capability    | `status` values                                 | When enabled                          |
| ------------- | ----------------------------------------------- | ------------------------------------- |
| `payments`    | `unrequested`, `pending`, `enabled`, `disabled` | Merchant can accept payments          |
| `settlements` | `unrequested`, `pending`, `enabled`, `disabled` | Merchant can receive bank settlements |

We recommend polling [Capabilities API](https://docs.mollie.com/reference/list-capabilities) endpoint periodically for all your connected accounts, not just during the onboarding. If a capability moves to `disabled` or gains new requirements during a periodic review, surface this in your platform and prompt your merchant to take the needed action. You can direct them to their own Mollie Web App where the required steps are listed.

<Callout icon="📘" theme="info">
  The `organizations.read` and `onboarding.read` [permission](https://docs.mollie.com/docs/permissions) scopes are required to access capability data for connected accounts. Ensure you are granted those before calling the endpoint.
</Callout>

## Disconnect merchants

A connection with your partner organization can be suspended in three ways:

* **Via the API**: call [Revoke tokens](https://docs.mollie.com/reference/oauth-revoke-tokens) to immediately end the connection from your side.
* **Via your Web App**: remove the client from the **Partners > Clients** (or **Sellers**) page in your Mollie partner dashboard.
* **Merchant-initiated**: your merchant can revoke access from their own Mollie account under **Authorized apps**. Your next token refresh will return an `invalid_grant` error; treat this as a disconnection signal and remove any stored tokens.