Core concepts

Key terms

A merchant (also called a connected account) is a business you onboard to Mollie.
A customer is that merchant's buyer, stored through the Customers API (cst_) for recurring billing.
A shopper is the person paying at checkout.

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. Balances 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 Capabilities API (beta).

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).
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).
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.

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 Application Fees 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.
Upfront routing fixes the split at payment creation. Delayed routing lets you hold funds until conditions are met (for example delivery confirmation).
Both upfront and delayed routing require split payments to be enabled on your account.

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 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.

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) and Onboard merchants.