Mollie Connect for Marketplaces - Example integration

This guide walks you through the basics of implementing Mollie Connect by registering an OAuth-compatible app, connecting your existing sellers with a Mollie account and facilitating payments on their behalf.

For this demonstration, we’ll first build an OAuth-compatible application called Bloomify - an online flower Marketplace connecting various flower shops, florists, and local boutiques and want to facilitate their payments via Bloomify.
We'll then walk you through linking an existing seller: in this case, Bouquet Studio, an imaginary boutique florist on specializing in locally sourced blooms.
Lastly, we will learn how to test and then start processing payments on your sellers's behalf and facilitate payouts using Mollie Connect functionality.

What to do in advance

Create a Mollie account.
(We recommend creating a partner account as it enables you to access all partner-related features of the Connect suite.)
Check that you’ve submitted all the necessary information about your business and wait for Mollie to verify your account.

Step 1: Set up OAuth app

In order to use Mollie Connect to onboard your sellers, you will have to first implement the OAuth authorization flow.
The flow starts with creating an OAuth-compatible application in your Mollie Dashboard: in this case, it is an app we are creating for Bloomify:

In your Dashboard click More -> Developers.
Select Your apps tab and click Create Application:

Fill in your app details and click Save:
Here we also opt in for the Co-Branded Onboarding: this means that you are in control of your sellers' experience during their account creation by incorporating your logo and brand colors into the onboarding process. This makes the onboarding experience more seamless and provides a trusted look and feel.

Now that our app is created, we can view our Client ID and Client Secret, which we will later use in the OAuth API requests:

Step 2: Connect sellers

The next step in the onboarding is to have your sellers connect their Mollie account/Organization to the app we just created to then accept payments on their behalf and facilitate payouts.
In this case, our existing seller is an imaginary boutique Bouquet Studio that offers bouquet arrangements and wants to facilitate their payments via Mollie.

📘
You can also create new organizations for your sellers using Client Links API that are then automatically connected to your partner account.

To connect Bouquet Studio to Bloomify, we will need to construct an Authorization URL with the parameters such as clientId, scope, state etc. which you then share with Bouquet Studio to connect their account to our app.
More on constructing the Authorization URL in our Authorize API reference.

📘
Mollie offers a Postman collection covering the latest version of the Mollie API. You can import this collection into your own Postman application to simplify your explorations of the Mollie API:

Get the Mollie Postman collection

Get Postman

Copy the final URL and redirect your seller to that authorization URL.
Once redirected, they will proceed through the authorization steps on Mollie's side (logging in and granting your app the requested permission to access their Mollie account):

At the end of the flow, Mollie will redirect the seller back to the redirect URL you specified, with a payload described in our Authorize API reference.
Use the auth_code from the redirect URI and exchange it for a refresh and access token. More on it here.
Securely store the refresh token in your database.

📘
In order to operate your seller's Mollie organization on their behalf, we use these OAuth App credentials and specifically the refresh token to obtain a new access token to authorize the API calls.

(Optional) We recommend to immediately perform a Get Onboarding API call and displaying the name of the connected Mollie organization to indicate that the connection was successful and checking whether settlements are enabled on the account (canReceiveSettlements: true).

Once your seller connects to your app, you can find their details and account status in your Dashboard under Sellers:

Step 3: Complete the onboarding

Now the seller must complete the verification process to start accepting payments:

While waiting for your seller to complete the onboarding, use the Onboarding status endpoint response to display the appropriate message.

Possible statuses are needs-data, in-review, and completed. If needs-data is returned, Mollie requires more information and the API response contains a _links/dashboard deep link to the seller’s co-branded Getting Started wizard.
We recommend including the link in your application with a clear call-to-action.

Once canReceivePayments flag is true, you can test if everything is set up correctly by creating your first payment.

Step 4: Test your payments

Before going live, you can simulate payments in the test mode where no real money transfers occur.

📘

Use Mollie test credentials to test credit/debit cards

Obtain a new access token using the stored refresh token to authorize the API calls on behalf of your seller.

For organization-level credentials (such as your OAuth access tokens), you can enable the test mode by setting the testmode parameter to true in your Create Payment API call.

{
    "amount":
    {
        "currency":"EUR",
        "value":"10.00"
    },
    "description":"This is a test payment",
    "redirectUrl":"https://bloomify.com/checkout/landing",
    "profileId":"pfl_zcfJRjkf6P",
    "testmode":true
}

Route payments with Split Payments

With Mollie Connect for Marketplaces you can route funds between connected seller accounts when creating payments via Payments API. This feature was built for cases where customers purchase goods from multiple sellers in a single basket.

Split Payments can be created by simply specifying a routing array in the Create Payment API. Each item in this array needs to contain an amount to be split to the sellers, and a destination which includes the organization id of the seller the funds should be split to.

You can split funds to one single seller or to multiple (2+) sellers and there is currently no limit on how many routes can be created for a single payment.

For example, in the API call below, we are routing the funds to two different sellers, org_1234 and org_5678 by specifying the organizationId:

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

Step 5: Go live

Before going live and starting processing transactions, make sure that:

Your seller finished the onboarding and their account is verified.
You are done with testing your setup and everything works as expected.
You enabled payment methods you plan to offer and they are activated in your organization.

If you checked all of the above, you can now go live and start accepting payments.
For organization-level credentials (such as your OAuth access tokens), you can enable live mode by setting the testmode parameter to false or simply omit the parameter.

For example, in the API call below, we are processing a transaction of 5.00 EUR using Split Payments (to a single seller) of1.00 EUR and we are doing it in the live mode:

POST https://api.mollie.com/v2/payments
{
	"amount": {
		"value": "5.00",
		"currency": "EUR"
	},
	"description": "Test split payment",
	"routing": [
		{
			"amount": {
				"currency": "EUR",
				"value": "1.00"
			},
			"destination": {
				"type": "organization",
				"organizationId": "org_1234"
			}
		}
	],
	"redirectUrl": "https://bloomify.com?success=true"
}

Now the setup is complete and you are ready to process payments on behalf of your sellers!