Docs
Start typing to search…

Connect for Platforms: Balance Transfers

Balance Transfers let you control the flow of funds between different organizations within your platform. Whether you’re collecting invoices, redistributing revenue or applying changes post-settlement - this feature allows you to do it all in one place, within Mollie’s ecosystem.

What is a Balance Transfer?

Balance Transfers move funds between two Mollie organizations that already own those funds.

It must not be used to process merchant or consumer funds on behalf of others or to:

  • Receive shopper funds into your platform and forward them to sellers.
  • Aggregate or split consumer payments or act as merchant of record for others.
  • Hold or escrow third-party funds, intermediate settlements or net consumer payments across multiple merchants.
  • Create pass-through “transit” flows where the platform becomes a part of the settlement.

It is allowed to be used for:

  • Collecting platform fees or royalties owed to the platform by a connected merchant (with prior consent).
  • Post-delivery adjustments between connected merchants, where both parties are the legal owners of the balances being moved.
  • Correcting or applying penalties that do not effect shopper funds or replace settlement.

Example use cases:

  • SaaS platforms collecting monthly or per-transaction fees.
  • Marketplaces adjusting balances post-delivery.
  • Franchisors charging revenue-based or fixed monthly fees.
📘

Partners are responsible for PSD2 compliance. Mollie may review and block transfers that indicate the platform is in the money flow. If unsure, contact your compliance advisor or Mollie support before going live.

Setup & Permissions

📘

Contact your Mollie point of contact to enable Balance Transfers in your Organization.

To use Balance Transfers, connect sub-merchants via your OAuth application with the following scopes:

  • balance-transfers.read
  • balance-transfers.write

Every time you create a Balance Transfer, ensure that both the source and destination accounts are:

  • Active
  • Can receive payments
  • Can send settlements
  • Have sufficient balance (validated via pre-execution reserve check)
🚧

You must have a documented consent from your sub-merchants authorizing balance movements.

How it works

  1. Authenticate the transfer using the source organization's access token.
  2. Initiate a transfer with an API call (see API Overview below).
  3. Track your transfer's status asynchronously using Webhooks or via the GET endpoint.

Transfers are always initiated between two Mollie merchant accounts. Transfers can be made between two of your users, or you can be either the source or the destination of the transfer.

API Overview

Create a transfer

To create a Balance Transfer, make a POST request to our Public API endpoint.

Descriptions you provide in source.description | destination.description will show up in Mollie dashboards and reports for both organizations.

POST /v2/connect/balance-transfers

{
    "amount": {
        "currency": "EUR",
        "value": "0.10"
    },
    "description": "transfer test",
    "destination": {
        "description": "description for the destination",
        "id": "org_12659708",
        "type": "organization"
    },
    "source": {
        "description": "description for the source",
        "id": "org_19120883",
        "type": "organization"
    },
    "testmode": false
}

Balance Transfer requests are processed asynchronously. Use the returned id to query your transfer's status or listen to any updates using Webhooks.

Get a transfer

Retrieve the current status of a specific transfer.

GET /v2/connect/balance-transfers/{id}

List transfers

Paginate through previous transfers. Supports the following query parameters: limit sort from testmode

GET /v2/connect/balance-transfers

Webhooks

To receive new updates for your transfers using Webhooks:

  • Set up a Webhook using our next-gen webhook framework.
  • Listen for status changes like: connect-balance-transfer.succeeded or connect-balance-transfer.failed.

If you subscribe to full payload (snapshot) webhooks, you can look at the field statusReason.code to find out the reason for a specific balance transfer status:

  • request_created - Balance transfer request was created.
  • success - Balance transfer completed successfully.
  • source_not_allowed - Balance transfers from the source organization are not allowed.
  • destination_not_allowed - Balance transfers to the destination organization are not allowed.
  • insufficient_funds - Source does not have enough balance.
  • invalid_source_balance - Invalid balance for source organization.
  • invalid_destination_balance - Invalid balance for destination organization.
  • transfer_request_expired - Request for balance transfer has expired.
  • transfer_limit_reached - Transfer limit has been exceeded.
{
    "_embedded": {
        "entity": {
            "amount": {
                "currency": "EUR",
                "value": "0.10"
            },
            "createdAt": "2025-10-07T11:59:09.05704Z",
            "description": "description for the initiator",
            "destination": {
                "description": "description for the destination",
                "id": "org_12659708",
                "type": "organization"
            },
            "executedAt": "2025-10-07T11:59:12.810532Z",
            "id": "cbtr_29mJGPbimEY4vspUWBFFJ",
            "mode": "live",
            "resource": "connect-balance-transfer",
            "source": {
                "description": "description for the source",
                "id": "org_19120883",
                "type": "organization"
            },
            "status": "succeeded",
            "statusReason": {
                "code": "success",
                "message": "Balance transfer completed successfully."
            }
        }
    },
    "_links": {
        "documentation": {
            "href": "https://docs.mollie.com/guides/webhooks",
            "type": "text/html"
        },
        "self": {
            "href": "https://api.mollie.com/v2/events/event_pWB8XELiETjy4tiqWBFFJ",
            "type": "application/hal+json"
        }
    },
    "createdAt": "2025-10-07T11:59:13.0Z",
    "entityId": "cbtr_29mJGPbimEY4vspUWBFFJ",
    "id": "event_pWB8XELiETjy4tiqWBFFJ",
    "resource": "event",
    "type": "connect-balance-transfer.succeeded"
}

Current limits

  • Default limit for live transfers is EUR 1,000 per month per sub-merchant (combined debits & credits).
  • There are currently no limits for test transfers (testmode : true).
📘

Need higher production limits? Reach out to your Mollie point of contact to set different transfer limits.

Legal notice

Mollie executes transfers a partner has initiated under the following circumstances:

  • The Partner initiating the transfer has their sub-merchant's consent.
  • The amount and purpose of the transfer are valid.

Partners are legally responsible for all submitted transfer requests along with the instructions they provided when initiated.

Updated 21 days ago

What’s Next