---
updatedAt: 2026-08-25T14:02:59.000Z
agentTools:
  projectIndex: https://docs.mollie.com/llms.txt
---

# Core concepts

## Key terms

A **merchant** (also called a **connected account**) is a business you onboard to Mollie. <br />A **customer** is that merchant's buyer, stored through the <Anchor target="_blank" href="https://docs.mollie.com/gu/reference/customers-api">Customers API</Anchor> (`cst_`) for recurring billing. <br />A **shopper** is the person paying at checkout.

<Callout icon="📘" theme="info">
  We use the term **merchant** for the onboarded business to keep it distinct from the <Anchor target="_blank" href="https://docs.mollie.com/gu/reference/customers-api">Customers API.</Anchor> In the Mollie Web App the same connected merchants are listed under **Partners > Clients**, and the onboarding API is the <Anchor target="_blank" href="https://docs.mollie.com/reference/client-links-api">**Client Links API**</Anchor>. The terms **client** and `client_id` refer to your OAuth app, not the onboarded business.
</Callout>

## Account model

Everything in Connect is built around a core set of entities that persist across onboarding, payments and balances.

* **Organization:** a Mollie account. Your platform is an organization and so is each merchant you connect.
* **Connected account (merchant):** a merchant organization linked to your platform using OAuth.
* **Profile:** a merchant's storefront configuration, holding its trading name, branding, website and the payment methods enabled on it. A merchant can have several profiles. A single profile can accept multiple currencies.
* **Balance:** the funds an organization holds at Mollie. <Anchor target="_blank" href="https://docs.mollie.com/docs/balance">Balances</Anchor> are set up per currency: an organization has a primary balance but may hold other balances. A payment in a currency you already hold settles to that balance and otherwise it converts to your primary balance.
* **Capability:** actions an organization is allowed to perform right now: accept payments, receive settlements, onboard customers etc. Capabilities sit at the organization level. You can check them via the <Anchor target="_blank" href="https://docs.mollie.com/reference/list-capabilities">Capabilities API</Anchor> (beta).

```mermaid
graph LR
  P["Platform (organization)"]
  P -->|OAuth| M["Connected account (organization)"]
  M --> PR[Profile]
  M --> BAL[Balance]
  M --> CAP[Capabilities]
  PR --> PM[Payment methods]
```

For a Marketplace, payments are owned by the platform and land in a holding balance held by Mollie before you route them to sellers.

## Typical funds flow

There are a few ways funds move in Mollie: a **pay-in** (money into a Mollie balance), an **internal transfer** (between Mollie balances) or a **payout** (out to a bank account). <br />Additionally, funds move in a form of application fees, routes, settlements and balance transfers.

### Connect for Platforms

For platforms, the **merchant** owns the payment. When the payment succeeds, Mollie credits the amount to the **merchant's balance** (minus Mollie's processing fee) and moves the application fee to your platform balance. Funds rest on the merchant's own Mollie balance (pending first, then available). <br />There is no separate **escrow account**. Application fees are **non-refundable** if the merchant refunds the shopper later. The merchant's available balance is then paid out to their bank based on the settlement schedule.

```mermaid
graph LR
  Shopper -->|Pay-in| MerchantBal[Merchant balance]
  MerchantBal -->|Application fee| PlatformBal[Platform balance]
  MerchantBal -->|Processing fee| MollieFees[Mollie fees]
  MerchantBal -->|Settlement| MerchantBank[Merchant bank]
```

See <Anchor target="_blank" href="https://docs.mollie.com/docs/application-fees">Application Fees</Anchor> for more information on limits, refunds and reporting.

### Connect for Marketplaces

For marketplaces, the pay-in lands in a **holding balance** (Mollie-held account where funds sit before you route them). You distribute funds to sellers via routes, either at checkout (upfront routing) or after the payment is paid (delayed routing, *recommended*). Your commission is the portion of funds you do not route - it stays on your marketplace balance. There is no separate commission parameter. <br />**Upfront** routing fixes the split at payment creation. **Delayed** routing lets you hold funds until conditions are met (for example delivery confirmation).<br />Both upfront and delayed routing require **split payments** to be enabled on your account.

```mermaid
graph LR
  Shopper -->|Pay-in| HB["Holding balance, held by Mollie"]
  HB -->|Route| SB[Seller balances]
  HB -->|Unrouted, your commission| MB[Marketplace balance]
  SB -->|Settlement| SBank[Seller banks]
  MB -->|Settlement| MBank[Your bank]
```

## Authentication: acting on behalf of a merchant

[OAuth](https://docs.mollie.com/docs/authentication-via-oauth) lets your platform act on a merchant's behalf without handling their credentials manually. The merchant grants your app a set of permissions (scopes), you then receive authentication tokens and can use them to call APIs on behalf of that merchant.

```mermaid
sequenceDiagram
  participant P as Platform
  participant M as Merchant
  participant Mo as Mollie
  P->>M: Connect with Mollie Client Link
  M->>Mo: Log in and grant scopes
  Mo-->>P: Redirect with authorization_code valid 30s
  P->>Mo: Exchange code for tokens Tokens API
  Mo-->>P: access_token 60 min and refresh_token persistent
  P->>Mo: API calls Bearer access_token
```

More on this in [Authentication (via OAuth)](https://docs.mollie.com/docs/authentication-via-oauth) and [Onboard merchants](https://docs.mollie.com/docs/connect-onboard-merchants).