Connect for Marketplaces: Onboarding customers

Next, we need to link new or existing customers to your OAuth app using Mollie Connect.

Onboarding customers

📘

Note

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

If your platform needs to connect new or existing customers without pre-filling their business information, choose our standard OAuth implementation:

1. Click More > Developers.
2. Select Your apps tab and copy Client ID and Client Secret of your application:

3. Construct an authorization URL with the parameters such as clientId, scope, state etc following the URL parameters section of the Authorize article.
   Then, you can send your merchant to that URL to take them to the authorization screen (typically this redirect sits behind a Connect with Mollie button).
4. Once they follow the URL, the OAuth authorize screen pops up and asks your customers to connect to Mollie and grant the necessary permissions:

5. After your customers finish the authorization steps, they are redirected back to the redirect URL you specified, which includes the code parameter with the authorization_code. This code expires after 30 seconds.
6. You need to fetch the authorization_code from the client's request, and use it to send a request to the Tokens API to generate a pair of credentials allowing you to create API requests on behalf of your customers: access_token and refresh_token.
   • The access_token you receive is temporary and expires after 60 minutes.
   • The refresh_token is persistent, so make sure you encrypt and store it securely in your application.
7. Once your customers click the link and connect to your OAuth app, they appear under the Sellers tab in your dashboard.

You can check out each organization to see more details about the account, such as which onboarding steps are remaining, the website profiles created, and payment methods enabled for those profiles.

Automating customer onboarding

Create an organization for your customer

For a seamless and automated Mollie onboarding experience of new customers, we will be using the Client Links API built on Mollie’s OAuth.

1. Send customer's information to the Create Client Link endpoint, with their business details. Pre-fillable data includes:

• Personal data of your customer:
  • Email
  • Given Name
  • Family Name
  • Locale
• Organization name
• Address
• Registration number
• VAT number

2. The API returns a clientLink in the response, which you will need to add additional URL parameters to before sharing it with your customer. This includes clientId, scope, state etc following the URL parameters section of the Authorize article.
   Once they follow the link, an organization is created with the prefilled information about their business:

3. The customer returns to the redirect_url of your OAuth application that you specified, and the regular OAuth flow follows.

When the link is first opened, Mollie also triggers an email to your customer's email address asking them to verify their email and set a new username and password.

Configure your customers' profiles

As your customers continue onboarding at Mollie, they will configure one or more website profiles.
Profiles represent merchant storefronts, allowing for multiple trade names or markets within one account. Payment methods and transactions are always associated with specific profiles.

For customers who already have a Mollie account, they may have already created and configured one or more profiles. We recommend asking them to select the profile that they wish to use to process payments through your platform. You can fetch a list of existing customer profiles via the Profiles API, or you can create and configure a new profile on your customer's behalf:

• Send data to create a new profile for your customer using the Create profile endpoint.
• Enable payment methods through the API (some methods may require additional activation steps).

Wait for your customers to complete the onboarding

While waiting for your customers to complete their onboarding, use the Onboarding status endpoint response to display the current status.

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 onboarding wizard. We recommend including the link in your application with a clear call-to-action.

Two milestones, canReceivePayments and canReceiveSettlements, indicate progress during onboarding. Display the following onboarding status messages:

Once canReceivePayments flag is true, you can create your first payment to test your integration.