Plugins-2 icon

Set up the connector

Integrate your Mirakl Marketplace with Adyen for Platforms.

Step 1: Create a Mirakl user for the Adyen Connector

To create a new operator user in Mirakl, you must have the Operator account users management and Operator account user roles management permissions. Read more about operator roles in Mirakl documentation.

Create a new user for the Adyen connector:

  1. In the Mirakl back office, go to Settings > Users > Operator account users.
  2. Under the Operator account users tab, select Add an operator account user.
    This opens a window to add the details for the new user.
  3. In the User name field, enter an email address for the user. 
    This email is required to sign in to Mirakl. Therefore, provide a shared, monitored address to ensure the integration can continue seamlessly even during personnel changes in your company.
  4. Select the checkboxes for the following roles:
    • Accounting and finance
    • Shop account management
    • Sales administration
    • API Access
    • Technical administration and security
  5. Select Save.

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.
    Code Label Description Type Shop account permissions
    adyen-v2-balance-account-id Balance account Your seller's unique balance account ID. Text
    Max length: 2000    		 Invisible
    adyen-v2-legal-entity-id Adyen Legal entity Your seller's unique legal entity ID. Text
    Max length: 2000    		 Invisible
    adyen-v2-account-holder-id Adyen Account holder Your seller's unique account holder ID. Text
    Max length: 2000    		 Invisible
    adyen-v2-transfer-instrument-id Adyen Transfer instrument The unique transfer instrument ID 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 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.

To learn more about configuring email templates, see Mirakl documentation.

Step 5: Send onboarding information to Adyen

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

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 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 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. 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 operator API key Your Mirakl operator API key for the Mirakl user you created.

Adyen settings

Setting Description
Balance platform name The name of your balance platform, as shown in your Balance Platform Customer Area.
Balance account ID The liable balance account. Get it from your Balance Platform Customer Area > Accounts & Balances > Balance accounts.
Balance Platform API credential The username and API key of your Configuration API and Transfers API web service user. Username format: ws@BalancePlatform.[YourBalancePlatform]. Get it from your Balance Platform Customer Area > Developers > API Credentials.
Scope (LEM) API credential The username and API key of your Legal Entity Management API web service user. Username format: ws@Scope.BalancePlatform.[YourBalancePlatform]. Get it from your Balance Platform Customer Area > 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 to confirm this date for both test and live environments.

Next steps

required
Onboard sellers

Learn how the onboarding process works with the Adyen Mirakl Connector.
required
Set up payment flows

Learn about splitting payments at captures, refunds, and chargebacks and seller payouts.