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
andClient 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:
- 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 arefresh
andaccess token
. More on it here.
Securely store therefresh 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 storedrefresh 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!
Updated about 1 month ago