Set up the connector

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:
   • Shop, Sales and Inventory 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 > Shop accounts.

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.	URL	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 different than their home country. 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:

• Connector settings
• Mirakl 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 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.