Connect: 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 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:
GET https://api.mollie.com/v2/balances
Authorization: Bearer <access_token_of_connected_customer>To retrieve the primary balance directly:
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 Balances API.
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 with the connected merchant's access token to check their current status:
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.
A merchant can have payments enabled while their settlements is still pending, so check each capability separately rather than treating onboarding as one.
| 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 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.
The
organizations.readandonboarding.readpermission scopes are required to access capability data for connected accounts. Ensure you are granted those before calling the endpoint.
Disconnect merchants
A connection with your partner organization can be suspended in three ways:
- Via the API: call 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_granterror; treat this as a disconnection signal and remove any stored tokens.
Updated 13 minutes ago