Guides

Connect for Marketplaces: Processing payments

Suggest Edits

Accepting payments

In its simplest form, setting up a payment requires only three steps: setting up the payment with our Payments API, sending the customer to our hosted checkout, and checking the payment status to verify that the payment was successful.

To set up and test your payment processing flow, refer to the Accepting Payments overview for a step-by-step guide on implementing the Payments API and testing your integration with the first sandbox transaction.

As we are just testing the flow and not processing actual transactions live yet, make sure to enable test mode by setting the testmode param to true.

Monetizing payments with Split payments

Overview

Splitting payments is a great choice when it comes to Marketplaces as it allows Mollie organizations to route funds between their connected customer accounts (i.e. sellers), which makes it possible for customers to purchase goods from multiple sellers in a single basket.
A Marketplace platform can then distribute the funds between the various parties, and even choose to retain a portion of those funds in their balance as a type of application fee.

In this setup, your platform is the owner of the payment, your rates are charged on your account directly and are not visible to your connected customers.
The chargeback liability also remains on your account.

Merchants can split funds to a single customer or to multiple (2+) customers. There is currently no limit on how many routes can be created for a single payment.

Some advantages of using Split payments are:

  • Ability to distribute, split and route payments between your platform and your connected customer accounts.
  • Flexibility to control the timing and frequency of your customers’ settlements from Mollie.
  • Great for use cases where multiple parties are involved in the payout.

📘

Example

Split Payments are great for use cases where multiple parties are involved in the pay-out side of the equation. Examples include business-to-consumer marketplaces or partners that service franchise businesses.
See how Q-Park now offers easy, automated payment solutions via their app, enhancing customer convenience and operational efficiency using Mollie Connect here.

Enabling Split payments

Split payments are not enabled by default. To enable them for your organization, complete this request form or contact your Mollie partner manager and they can enable Split payments for your account.

How to create Split payments

Once marketplace features have been enabled on your account, and you have a customer account connected to your platform, you can start sending parts of each payment to your customers' balance.

Split Payments are created using the Payments API, by simply specifying a routing array in the Create payment API call.

Each item in this array needs to contain an amount to be split to the customer, and a destination which includes the organization id of the customer the funds should be split to:

{
	"amount": {
		"value": "5.00",
		"currency": "EUR"
	},
	"description": "Testing split payments",
	"routing": [
		{
			"amount": {
				"currency": "EUR",
				"value": "1.00"
			},
			"destination": {
				"type": "organization",
				"organizationId": "org_1234"
			}
		}
	],
	"redirectUrl": "https://example.com?success=true"
}

Example API Call

In the example below, we will route €3,50 of a €10,00 payment to the connected account org_23456, and €4,00 to the connected account org_56789

On our own account, we will receive the remainder of €2,50 minus any payment fees charged by Mollie.

curl -X POST https://api.mollie.com/v2/payments \
    -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
    -d "amount[currency]=EUR" \
    -d "amount[value]=10.00" \
    -d "description=My first routed payment" \
    -d "redirectUrl=https://webshop.example.org/order/12345/" \
    -d "webhookUrl=https://webshop.example.org/payments/webhook/" \
    -d "routing[0][amount][currency]=EUR" \
    -d "routing[0][amount][value]=3.50" \
    -d "routing[0][destination][type]=organization" \
    -d "routing[0][destination][organizationId]=org_23456" \
    -d "routing[1][amount][currency]=EUR" \
    -d "routing[1][amount][value]=4.00" \
    -d "routing[1][destination][type]=organization" \
    -d "routing[1][destination][organizationId]=org_56789"

HTTP/1.1 201 Created
Content-Type: application/hal+json; charset=utf-8

{
    "resource": "payment",
    "id": "tr_7UhSN1zuXS",
    "amount": {
        "value": "10.00",
        "currency": "EUR"
    },
    "description": "My first routed payment",
    "status": "open",
    "redirectUrl": "https://webshop.example.org/order/12345/",
    "webhookUrl": "https://webshop.example.org/payments/webhook/",
    "routing": [
        {
            "resource": "route",
            "id": "rt_k6cjd01h",
            "amount": {
                "value": "2.50",
                "currency": "EUR"
            },
            "destination": {
                "type": "organization",
                "organizationId": "me"
            }
        },
        {
            "resource": "route",
            "id": "rt_9dk4al1n",
            "amount": {
                "value": "3.50",
                "currency": "EUR"
            },
            "destination": {
                "type": "organization",
                "organizationId": "org_23456"
            }
        },
        {
            "resource": "route",
            "id": "rt_ikw93sr2",
            "amount": {
                "value": "4.00",
                "currency": "EUR"
            },
            "destination": {
                "type": "organization",
                "organizationId": "org_56789"
            }
        }
    ]
    "...": { }
}

As soon as the payment is completed, the €3,50 and €4,00 will become available on the balance of the connected accounts, and the €2,50 will become available on the balance of your platform account.

Delaying settlement

The settlement of a routed payment can be delayed on payment level, by specifying a releaseDate on a route when creating a payment.

For example, the funds for the following payment will only become available on the balance of the connected account org_23456 on 1 January 2025, and on the balance of the connected account org_56789 on 12 January 2025:

curl -X POST https://api.mollie.com/v2/payments \
    -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
    -d "amount[currency]=EUR" \
    -d "amount[value]=10.00" \
    -d "description=My first delayed payment" \
    -d "redirectUrl=https://webshop.example.org/order/12345/" \
    -d "webhookUrl=https://webshop.example.org/payments/webhook/" \
    -d "routing[0][amount][currency]=EUR" \
    -d "routing[0][amount][value]=3.50" \
    -d "routing[0][destination][type]=organization" \
    -d "routing[0][destination][organizationId]=org_23456" \
    -d "routing[0][releaseDate]=2025-01-01" \
    -d "routing[1][amount][currency]=EUR" \
    -d "routing[1][amount][value]=4.00" \
    -d "routing[1][destination][type]=organization" \
    -d "routing[1][destination][organizationId]=org_56789" \
    -d "routing[1][releaseDate]=2025-01-12"

HTTP/1.1 201 Created
Content-Type: application/hal+json; charset=utf-8

{
    "resource": "payment",
    "id": "tr_2qkhcMzypH",
    "amount": {
        "value": "10.00",
        "currency": "EUR"
    },
    "description": "My first routed payment",
    "status": "open",
    "redirectUrl": "https://webshop.example.org/order/12345/",
    "webhookUrl": "https://webshop.example.org/payments/webhook/",
    "routing": [
        {
            "resource": "route",
            "id": "rt_k6cjd01h",
            "amount": {
                "value": "2.50",
                "currency": "EUR"
            },
            "destination": {
                "type": "organization",
                "organizationId": "me"
            }
        },
        {
            "resource": "route",
            "id": "rt_9dk4al1n",
            "amount": {
                "value": "3.50",
                "currency": "EUR"
            },
            "destination": {
                "type": "organization",
                "organizationId": "org_23456"
            },
            "releaseDate": "2025-01-01"
        },
        {
            "resource": "route",
            "id": "rt_ikw93sr2",
            "amount": {
                "value": "4.00",
                "currency": "EUR"
            },
            "destination": {
                "type": "organization",
                "organizationId": "org_56789"
            },
            "releaseDate": "2025-01-12"
        }
    ]
    "...": { }
}

It is possible to update the release date of a transaction before it reaches the connected account’s available balance, as long as the consumer has already completed the payment, by updating the payment route object:

curl -X PATCH https://api.mollie.com/v2/payments/tr_2qkhcMzypH/routes/rt_9dk4al1n \
    -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
    -d "releaseDate=2026-01-01"

HTTP/1.1 200 OK
Content-Type: application/hal+json; charset=utf-8

{
    "resource": "route",
    "id": "rt_9dk4al1n",
    "amount": {
        "value": "7.50",
        "currency": "EUR"
    },
    "destination": {
        "type": "organization",
        "organizationId": "org_23456"
    },
    "releaseDate": "2026-01-01"
}

The release date can be up to two years from the day of the payment’s creation. For test payments, this limit is 10 days.

Multicurrency support

Currently, Split Payments feature supports EUR and GBP payments but does not offer multicurrency conversion: the routes need to be either in the currency of the payment or in the currency of the submerchant but not both.

Invoicing

Mollie invoices Marketplace platforms for the transaction fees and connected seller fees every month. Sellers might choose to charge the consumer an additional fee by retaining an amount in their own account balance to cover the transaction fees or take a cut of the funds that would otherwise be allocated to the sellers. In both cases, the platform would need to independently invoice the seller(s) for this amount.

Refunds and chargebacks

Split payments can be both partially and fully refunded.

  • To process a full refund for a split payment, a request can be made to the Refunds API with reverseRouting set to true. This will deduct the amount that was originally split from the balance of each connected seller account and refund the full amount.
  • For partial refunds, a routingReversals array must be sent through to the Refunds API which is similar to the routing array provided when the payment is initially created. This array defines how much should be deducted from which seller account.
    You can’t reverse more than what was originally sent to that seller.

As the transaction owner, Marketplace bears the risk of chargebacks and those will be deducted from the balance of the Marketplace platform.

Updated 2 months ago