Connect: Balance Transfers

Balance Transfers allow you to 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 affect 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.

Setup & Permissions

To use Balance Transfers, connect your sub-merchants via 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 and can receive payments
• Can send settlements
• Have sufficient balance (validated via pre-execution reserve check)

How it works

1. Authenticate the transfer using the source organization's access token.
2. Initiate a transfer with an API call to Balance Transfers API.
3. Track your transfer's status asynchronously using Webhooks or via the GET endpoint.

API Overview

Create a transfer

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

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

List transfers

GET /v2/connect/balance-transfers

Supports query parameters: limit sort from testmode

Webhooks

To receive updates for your transfers using Webhooks:

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

Status reason codes:

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

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

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.