Guides

Connect for Platforms: Example integration

Suggest Edits

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

For this demonstration, we’ll first build an OAuth-compatible application called Circle that links gyms offering various fitness classes and wants to facilitate their payments via Circle.
We'll then walk you through linking an existing customer: in this case, FitnessFlow, an imaginary gym that offers subscription-based fitness classes.
Lastly, we will learn how to test and then start processing payments on your customer'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 customers, 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 Circle:

  1. In your Dashboard click More -> Developers.
  2. Select Your apps tab and click Create Application:
  1. 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 customers' 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.
  1. 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 customers

The next step in the onboarding is to have your customers 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 customer is an imaginary gym FitnessFlow that offers online fitness classes and wants to facilitate their subscription payments via Mollie.

📘

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

  1. To connect FitnessFlow to Circle, we will need to construct an Authorization URL with the parameters such as clientId, scope, state etc. which you then share with FitnessFlow 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:

  1. Copy the final URL and redirect your customer 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):
  1. At the end of the flow, Mollie will redirect the customer back to the redirect URL you specified, with a payload described in our Authorize API reference.
  2. 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 customer'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.

  1. (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.

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

Step 3: Complete the onboarding

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

While waiting for your customer 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 customer’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 customer.

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://circle.com/checkout/landing",
    "profileId":"pfl_zcfJRjkf6P",
    "testmode":true
}

Add Application Fee

With Mollie Connect you can monetize payments by charging Application fees on your customers' payments by passing a parameter applicationFee when creating payments via Payments API.

For example, in the API call below, the consumer pays 10.00 EUR to your customer with an added 1.50 EUR Application fee.
Once the transaction is successful, Mollie will move 1.50 EUR to the partner’s balance and will settle the amount minus transaction fee to the customer's balance.

{
    "amount":
    {
        "currency":"EUR",
        "value":"10.00"
    },
    "description":"I can accept payments now",
    "redirectUrl":"https://circle.com/checkout/landing",
    "profileId":"pfl_zcfJRjkf6P",
    "applicationFee":
    {   
        "amount":
        {
            "currency":"EUR",
            "value":"1.50"
        },
        "description":"This is Application fee"
    },
    "testmode":true
}

Step 5: Go live

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

  • Your customer 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 10.00 EUR with the added Application fee of 1.50 EUR and we are doing it in the live mode:

{
    "amount":
    {
        "currency":"EUR",
        "value":"10.00"
    },
    "description":"This is an actual payment",
    "redirectUrl":"https://circle.com/checkout/landing",
    "profileId":"pfl_zcfJRjkf6P",
    "applicationFee":
    {   
        "amount":
        {
            "currency":"EUR",
            "value":"1.50"
        },
        "description":"This is Application fee"
    }
}

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

Updated about 15 hours ago