Skip to main content
If your platform is using Mangopay’s Mirakl Connector and partnering with a third-party PSP for funds acquisition, then you need to set up custom fields on your Mirakl Orders and integrate them in your API calls.
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"
        }
    ]
...