Platforms are able to use third-party acquirers, alongside Mangopay as an acquirer not, and then benefit from Mangopay’s wallet and payout capabilities. Mangopay Echo provides transparency on funds acquired by other PSPs by declaring them as Intents and connecting them with the funds that then arrive in the Mangopay environment. The Mirakl Connector, which your platform is using, takes care of declaring Intents for all Mirakl Orders, regardless of whether the payments are processed by a third-party PSP or by Mangopay. So that the orders can be processed correctly, however, we require you to enrich Mirakl Orders with certain data points. Furthermore, in the event that your third-party PSP doesn’t provide settlement files today, you need to request that they do so you can send them to Mangopay.

​
Confirm your PSP provides settlement files

Applies to: Any platform using a third-party PSP for funds acquisition (whether the platform uses the Mirakl Connector or not)
Settlement data consists of:
  • A list of transactions and details for each: type (e.g. payment, refund, chargeback), identifiers, amounts, date, status information, etc.
  • Summary data relating to the settlement of those transactions: date of settlement, total amount sent to your platform, total amount of commission retained by the PSP, etc.
Many PSPs provide daily settlement files, but it is possible that your provider doesn’t. In this case, you need to request that they start making files available to you, ideally daily.
Best practice – Request settlement files as soon as possible (if not already provided)If your PSP doesn’t provide settlement files today, you need to request that they do as soon as possible.This data is essential for regulatory compliance and Mangopay relies on your partner PSP to provide you the files.

​
Enrich Mirakl Connector integration

Applies to: Any platform using a third-party PSP for funds acquisition and using the Mirakl Connector
Note – If using multi-capture, use order line custom fieldsThe connector supports single capture (one capture per commercial_order) and multi-capture (one capture per logistic_order or multiple captures per logistic_order).If you use multiple captures per logistic_order, use order line custom fields (order_line_additional_fields) instead of order custom fields.

​
1. Create custom Order fields in the Mirakl Dashboard

Mirakl allows its operators to create custom data fields (for Stores, Orders, etc.) for specific business needs. Mangopay’s Mirakl Connector relies on these custom fields to standardize the transactional data that is not always present in Orders. Without these fields, Mangopay Echo can’t declare external payments (called Intents in the Echo solution) or reconcile and release funds.

​
How to create fields

To create custom fields in the Mirakl Dashboard:
  1. Navigate to Settings in the sidebar menu.
  2. Select the entity: Orders
  3. Go to the Custom fields tab.
  4. Click Create custom field and fill in the required details such as Label, Code, Type, and Description.
Follow the specifications in the table below exactly. For the Mirakl settings not mentioned below we recommend:
  • Store account permissions: Invisible or Read only
  • Required field: No
There are no requirements for the Label, which is your custom display name.

​
Fields to create

CodeDescriptionType (Mirakl Dashboard)
mgp-external-provider-nameThe name of the external provider processing the transaction.Single values list containing the relevant value(s) exactly as they appear in the supported external providers.
mgp-external-processing-dateThe date at which the transaction was created.Date (ISO 8601 format)
mgp-external-provider-referenceThe unique identifier of the transaction at the provider level.Text (Max: 2000 char.)
mgp-external-merchant-referenceThe unique identifier of the transaction at the merchant level.Text (Max: 2000 char.)
mgp-external-provider-payment-methodOne of the supported payment methods used to process the transaction.Single values list containing the relevant values exactly as they appear in the supported payment methods.
Best practice – Use list values not text stringsThe data values sent in mgp-external-provider-name and mgp-external-provider-payment-method must match the supported enum values linked above.Therefore, it is better to use the Mirakl Single values list format with the specified values rather than free text. In the Mirakl API this format is LIST with accepted_values.Note that the payment method is not required by Mangopay, so if you make it required on Mirakl then all values must be in the supported values.

​
2. Integrate the custom Order fields into your Mirakl API calls

Now that the fields have been created, you need to integrate them on your calls to the Mirakl API for Orders. The following fields are required for correct processing by Mangopay Echo:
FieldRequiredExpected values
mgp-external-provider-nameYesOne of the supported external providers.
mgp-external-processing-dateYesISO 8601 date time in UTC (YYYY-MM-DDTHH:MM:SSZ)
mgp-external-provider-referenceYesString
mgp-external-merchant-referenceNoString
mgp-external-provider-payment-methodNoOne of the supported payment methods. If the payment method is not supported, this field can be left blank (provided you created it as not required).
You can send the data on the Mirakl endpoints:
  • OR01 when you create an Order – this is recommended
  • OR31 by editing an existing Order, if the data becomes available after creation
Note – Incomplete custom fields blocks release of fundsYou should provide the custom field data as early as possible in the flow.With this information, the Mirakl Connector calls the Mangopay API to declare the order details to Mangopay based on the Mirakl Order status. It creates, captures and refunds Intents.Without this custom field data, the Mirakl Connector cannot reconcile the Order and its settlement with Intents, preventing the release of funds to the seller.

​
Example of custom fields in Mirakl API call

...
    "order_additional_fields": [
        {
            "code": "mgp-external-provider-name",
            "type": "LIST",
            "value": "ADYEN"
        },
        {
            "code": "mgp-external-processing-date",
            "type": "DATE",
            "value": "2013-10-21T13:28:06.419Z"
        },
        {
            "code": "mgp-external-provider-reference",
            "type": "STRING",
            "value": "b8fd937e-f1ce-4ad7-9744-59797957beeb"
        },
        {
            "code": "mgp-external-merchant-reference",
            "type": "STRING",
            "value": "6f9b2ec2-d51e-4193-ac78-a18589f7d8af"
        },
        {
            "code": "mgp-external-provider-payment-method",
            "type": "LIST",
            "value": "VISA"
        }
    ]
...

​
Provide settlement files to Mangopay

Applies to: Any platform using a third-party PSP for funds acquisition (whether the platform uses the Mirakl Connector or not)
If your platform is using a third-party PSP for funds acquisition, you also need to send settlement data to Mangopay for reconciliation. The payment intent declarations are created automatically by the Mirakl Connector, but the settlement data must be provided by the platform. To do this, your platform needs to send CSV files to a dedicated endpoint as soon as they become available. Read more about the process and requirements in the guide:

Guide

Read how to provide settlement files to Mangopay

Guide

Read about Echo integration

Endpoints

POST Create a Settlement