---
title: "Set up the connector"
description: "Integrate your Mirakl Marketplace with Adyen for Platforms."
url: "https://docs.adyen.com/plugins/mirakl/set-up-the-connector"
source_url: "https://docs.adyen.com/plugins/mirakl/set-up-the-connector.md"
canonical: "https://docs.adyen.com/plugins/mirakl/set-up-the-connector"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# Set up the connector

Integrate your Mirakl Marketplace with Adyen for Platforms.

[View source](/plugins/mirakl/set-up-the-connector.md)

## Step 1: Create an access token for the Adyen Mirakl connector

Read more about generating access tokens in the [Mirakl documentation](https://help.mirakl.com/docs/customers/page/topics/Mirakl/get_started/generate_access_tokens.html).

To create an access token:

1. In the Mirakl back office, go to **Settings** > **Platform** > **API integrations**.
2. Select **Create API integration**.
3. Select the scope **Operator API**.
4. Select **Access token**.
5. Select **Create**, then copy the token and store it securely.

## Step 2: Add custom fields to Mirakl

To initiate the KYC verification checks and start processing split payments, you need to add custom fields in your Mirakl back office. The connector maps each custom field to an Adyen field and populates these fields when a seller's shop is synced with Adyen.

1. In the Mirakl backoffice, go to **Settings** > **Shops** > **Profile configuration**.

2. Select the **Custom fields** tab.

3. Select **Add a custom field**.

4. Create the following custom fields.

   * For all custom fields, select **Marketplace** for the **Platform models** field.
   * These fields must **not** be marked **required**.

If you have set up other custom fields that are marked as required, inform your Adyen contact. Required fields can prevent the connector from working correctly.

| Code                              | Label                     | Description                                                                                                                                                                                                                                           | Type                  | Shop account permissions |
| --------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------ |
| `adyen-v2-balance-account-id`     | Balance account           | Your seller's unique [balance account ID](/marketplaces/onboard-users/onboarding-steps).                                                                                                                                                              | Text Max length: 2000 | Invisible                |
| `adyen-v2-legal-entity-id`        | Adyen Legal entity        | Your seller's unique [legal entity ID](/marketplaces/onboard-users/onboarding-steps).                                                                                                                                                                 | Text Max length: 2000 | Invisible                |
| `adyen-v2-account-holder-id`      | Adyen Account holder      | Your seller's unique [account holder ID](/marketplaces/onboard-users/onboarding-steps).                                                                                                                                                               | Text Max length: 2000 | Invisible                |
| `adyen-v2-transfer-instrument-id` | Adyen Transfer instrument | The unique [transfer instrument ID](/marketplaces/onboard-users/onboarding-steps) representing your seller's bank account.                                                                                                                            | Text Max length: 2000 | Invisible                |
| `adyen-v2-hop-url`                | HOP Url                   | The link to the [generated Hosted Onboarding Page](/marketplaces/onboard-users/onboarding-steps) where your sellers can provide the details required for the KYC checks.                                                                              | Link                  | Read-only                |
| `adyen-kyc-vat`                   | Vat Number for KYC        | Only required if you need to make payouts to sellers who have a different VAT number for invoice purposes, because they operate in a country/region different than their home country/region. The VAT number of the parent entity for the KYC checks. | Text Max length: 2000 | Read write               |
| `adyen-v2-original-channel`       | Original Shop Channel     | Only required if you are using multiple channels. The first channel that was assigned to this shop.                                                                                                                                                   | Text Max length: 2000 | Invisible                |

5. Select **Confirm**.

## Step 3: Enable features in Mirakl

Contact Mirakl's support team to enable the following features for your marketplace:

* **KYC status**: required for the connector to update Mirakl about the results of KYC checks and if applicable, further actions required.
* **Payment confirmation**: required for the connector to mark invoices as **Paid**, allowing you to differentiate between invoices that have the **Pending payment** and **Paid** status.

## Step 4: Update email settings in Mirakl

The connector uses email notifications to inform you of any issues, for example, when payouts or the synchronization between Mirakl and Adyen fails.

After the **KYC status** feature is enabled for your marketplace, Mirakl will also send emails to your sellers about the status of their KYC checks. We recommend to change the default template for a KYC failure to a custom one.

To change the email template for a failed KYC:

1. In the Mirakl back office, go to **Settings** > **Platform** > **Notifications**.
2. Under the **Email Templates** tab, select the **Shop account KYC failed** template.
3. Replace the subject and body with our [Email template](/plugins/mirakl/set-up-the-connector/email-template.txt).

To learn more about configuring email templates, see [Mirakl documentation](https://help.mirakl.net/bundle/customers/page/topics/Mirakl/mmp/Operator/config_email_templates.html).

## Step 5: Send onboarding information to Adyen

To onboard you to the connector, we require the following information from you:

* [Connector settings](#connector-settings)
* [Mirakl settings](#mirakl-settings)
* [Adyen settings](#adyen-settings)

Reach out to your Adyen contact to provide this information.

### Connector settings

| Setting                                       | Description                                                                                                                                                                                                                                |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Hosted Onboarding Page (HOP) marketplace name | Your marketplace's name that appears in the hyperlink that takes sellers back to your HOP return URL on the welcome page. (**Back to MARKETPLACE\_NAME**)                                                                                  |
| HOP return URL                                | The URL sellers will be redirected to after providing the required data for KYC checks. This is usually the URL of your marketplace.                                                                                                       |
| Operator emails                               | The email addresses to receive notifications about the shop synchronization or invoices.                                                                                                                                                   |
| Mirakl HOP questions count                    | To ensure security in the KYC process, you can protect the link to the HOP with a series of questions that only your seller knows how to answer. HOP will only load once all questions are answered correctly. The default value is **5**. |
| Maximum Invoice Retry Count                   | The maximum amount of retries after an invoice payout fails. The default value is **10**.                                                                                                                                                  |
| Locale                                        | The language of the text in the HOP. The default value is **en-US** (English). Set to [another locale](/marketplaces/onboard-users/customize-hosted-onboarding#page-language) to render the page in a different language.                  |

You can decide to enable the following additional settings in the connector. When providing onboarding data, inform your Adyen contact whether these features are enabled or disabled.

| Setting                  | Description                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Manage Payment Block** | If there is a payment balance issue, KYC issue, or account sync issue with a seller, the [block payments flag on Mirakl](https://help.mirakl.net/bundle/customers/page/topics/Mirakl/integrating_mirakl/pay_sellers/block_seller_payments.html) is set automatically, meaning that the seller will be skipped in the billing cycle. The default value is **enabled**. |
| **Use Subscription**     | Separates commission payouts and subscription payouts if enabled. The default value is **disabled**. When disabled, the connector triggers a single payout for commission and subscription payouts.                                                                                                                                                                   |
| **Unsuspend New Shops**  | Automatically unsuspends new shops in Mirakl after KYC success. The default value is **enabled**. The seller status in Adyen is determined separately.                                                                                                                                                                                                                |

### Mirakl settings

| Setting             | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| URL                 | The service account URL of your Mirakl marketplace instance. |
| Mirakl Access Token | Required for the connector to access Mirakl's APIs.          |

### Adyen settings

| Setting                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------- |   |
| Balance platform name           | The name of your balance platform, as shown in your [Customer Area](https://ca-test.adyen.com/).                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Balance account ID              | The liable balance account. Get it from your [Customer Area](https://ca-test.adyen.com/) > **Accounts & Balances** > **Balance accounts**. This Balance account ID, where needed, should retain sufficient funds for scenarios like negative commissions. Otherwise, there is a risk of failed transfers.                                                                                                                                                                                                                                    |
| Balance Platform API credential | The username and API key of your [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) and [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview) web service user. Username format: `ws@BalancePlatform.[YourBalancePlatform]`. Get it from your [Customer Area](https://ca-test.adyen.com/) > **Developers** > **API Credentials**. Make sure the [**Balance Platform BCL** ](/marketplaces/manage-access/webservice-roles#frequently-used-roles)role is enabled for your user. |
| Scope (LEM) API credential      | The username and API key of your [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) web service user. Username format: `ws@Scope.BalancePlatform.[YourBalancePlatform]`. Get it from your [Customer Area](https://ca-test.adyen.com/) > **Developers** > **API Credentials**.                                                                                                                                                                                                                    |

## Step 6: Schedule synchronizations between Mirakl and Adyen

There are three different types of synchronizations that happen between Mirakl and Adyen:

* **Partial Sync**: synchronizes the shops which have been modified since the last sync.
* **Full Sync**: synchronizes all shops.
* **Start Invoice Sync**: schedules payouts.

For the **Start Invoice Sync**, you additionally need to inform Adyen of the date the invoice sync should start from. This is to avoid syncing older invoices. For example, if you have an invoice generated on June 1st, the sync must be configured to start from May 31st to make sure this invoice is picked up.

Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to confirm this date for both test and live environments.

## Next steps

[required](/plugins/mirakl/onboard-sellers)

[Onboard sellers](/plugins/mirakl/onboard-sellers)

[Learn how the onboarding process works with the Adyen Mirakl Connector.](/plugins/mirakl/onboard-sellers)

[required](/plugins/mirakl/set-up-payment-flows)

[Set up payment flows](/plugins/mirakl/set-up-payment-flows)

[Learn about splitting payments at captures, refunds, and chargebacks and seller payouts.](/plugins/mirakl/set-up-payment-flows)
