> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Third-party PSPs with Echo

Thanks to Mangopay’s flexible wallet system, platforms are able to use third-party acquirers instead of Mangopay pay-ins and then benefit from Mangopay’s wallet and payout capabilities.

[Echo](/guides/echo), Mangopay’s unified solution for platforms working with third-party acquirers, is integrated into the Mirakl Connector. This means your platform can benefit from flexibility with their acquirers, maximum compliance, and visibility on the flow of funds, all with minimal development effort.

If you are working with a third-party PSP and Mangopay’s Mirakl Connector, then the connector automatically:

* Creates Intents for all Mirakl Orders, both those processed by your partner and by Mangopay
* Handles Intent Refunds and Disputes
* Creates Splits to transfer the acquired funds to your sellers
* Retrieves any adjustments that need to be made in case of manual invoices, discounts, etc.
* Requests payouts once all reconciliation is successful

## Setup

### Onboarding

Before your platform can start integrating, Mangopay needs to know:

* The third-party PSP(s) you are working with
* The currencies in which you process transactions

Then, for each combination of PSP and currency, Mangopay needs to create (or use the existing):

* Dedicated Escrow Wallet
* Virtual Account attached to the Escrow Wallet

The Virtual Account is the IBAN that will receive the funds for escrow. The process above is the same for each `ClientId` you use, whether in Sandbox or Production.

### Obtaining settlement data from your PSP

Your third-party PSP needs to provide you with settlement data regarding the transactions that they process on your behalf.

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.

This data is essential for regulatory compliance and Mangopay relies on your partner PSP to provide you the files.

## Integration

All platforms using the Mirakl Connector and Echo are required to complete the following integration steps:

### 1. Enrich Mirakl Orders

To enable the Mirakl Connector to create Intents, your platform needs to create custom fields on Mirakl Orders and then send those fields on your Mirakl API calls.

The custom fields become the `ExternalData` of the Intent.

For details, see the [custom fields guide](/connectors/mirakl/acquiring/echo/custom-fields) **→**

### 2. Send settlement files to Mangopay

While the Mirakl Connector automatically creates payment Intents, your platform needs to provide settlement data from your PSP regarding the transactions it processes.

Your platform needs to integrate a set of endpoints to send the settlement data from your PSP to Mangopay. You also need to format the data according to Mangopay's format before sending it via the API.

You should send files to Mangopay as soon as the data is available from your provider, ideally daily.

For more details, see [how to send settlement files to Mangopay](/guides/echo#how-to-send-a-settlement-file-to-mangopay) **→**

### Platforms with 1P flows

If your platform also operating first-party (1P) transactions, then additional integration is required because these transactions are not visible to the Mirakl Connector. In 1P flow, your platform is the beneficiary of the transaction, selling directly to the user as traditional e-commerce.

If this is the case, the your platform needs to integrate [Echo](/guides/echo) directly for all 1P flows:

* Create Intents for transactions involving **only 1P baskets**
* Add 1P `LineItems` to Intents created by the Mirakl Connector in **mixed baskets** (1P and 3P)
* Track the payment lifecycle for 1P funds in case of refunds or disputes
* Create and execute Splits for 1P funds

## Activation - New platforms

For new platforms, as part of your go-live, Echo is fully enabled on the Mirakl Connector.

For existing platforms, see the [dedicated section below](#existing-platforms).

## Orders to Intents and Splits

The rest of this guide aims to give you an understanding of how the Mirakl Connector works to assist with your integration.

<div className="block dark:hidden">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFFFFF',
        'primaryTextColor': '#2D0F37',
        'primaryBorderColor': '#2D0F37',
        'lineColor': '#2D0F37',
        'secondaryColor': '#FFFFFF',
        'tertiaryColor': '#FFFFFF',
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#E0DBE1",
        'noteBkgColor': "#E0DBE1",
        'noteTextColor': '#2D0F37'
      }
    }
  }%%
  sequenceDiagram
  participant Platform
  participant Mirakl
  participant MiraklConnector as Mirakl Connector
  participant Echo

  Platform->>Mirakl: Create Order (OR01)
  Platform->>Mirakl: Add payment details (OR01/OR31)
  MiraklConnector->>Mirakl: Get new Orders (OR11)
  MiraklConnector->>Mirakl: Check custom fields
  MiraklConnector->>Mirakl: Get transaction Lines (TL02)
  MiraklConnector->>Echo: Create Intent
  MiraklConnector->>Echo: Capture Intent
  MiraklConnector->>Echo: Create Split
  Platform->>Echo: Fund escrow wallet
  Platform->>Echo: Send settlement file
  MiraklConnector->>Echo: Execute Split
  ```
</div>

<div className="hidden dark:block">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': "#090D0D",
        'primaryTextColor': "#FFFFFF",
        'primaryBorderColor': "#FFFFFF",
        'lineColor': "#FFFFFF",
        'secondaryColor': "#090D0D",
        'tertiaryColor': "#090D0D",
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#12282F",
        'noteBkgColor': "#090D0D",
        'noteTextColor': "#FFFFFF"
      }
    }
  }%%
  sequenceDiagram
  participant Platform
  participant Mirakl
  participant MiraklConnector as Mirakl Connector
  participant Echo

  Platform->>Mirakl: Create Order (OR01)
  Platform->>Mirakl: Add payment details (OR01/OR31)
  MiraklConnector->>Mirakl: Get new Orders (OR11)
  MiraklConnector->>Mirakl: Check custom fields
  MiraklConnector->>Mirakl: Get transaction Lines (TL02)
  MiraklConnector->>Echo: Create Intent
  MiraklConnector->>Echo: Capture Intent
  MiraklConnector->>Echo: Create Split
  Platform->>Echo: Fund escrow wallet
  Platform->>Echo: Send settlement file
  MiraklConnector->>Echo: Execute Split
  ```
</div>

### Creating Intents

<Note>
  **Note – Onboard sellers before accepting shop orders**

  Intents cannot be created if one or more shops do not have a corresponding Mangopay User.

  Ensure all shops with orders are [onboarded](/connectors/mirakl/sellers#mangopay-account-creation) before allowing them to accept orders.
</Note>

The Mirakl Connector creates Echo Intents and Splits on the basis of the information it finds in Mirakl Orders.

Intents are created at the level of the Mirakl Commercial Order, which represents the payment authorization. Intents are created when the Mirakl Transaction Lines are payable. In most workflows, this occurs when the order is marked as paid in Mirakl, typically via the PA01 endpoint. If you are unsure when this is triggered in your workflow, consult your Mirakl specialist.

#### Single capture and multi-capture

The connector supports single capture (one capture per `commercial_order`) and multi-capture (one capture per `logistic_order` or multiple captures per `logistic_order`).

When [creating the custom fields](/connectors/mirakl/acquiring/echo/custom-fields), if you use multiple captures per `logistic_order`, use order line custom fields (`order_line_additional_fields`) instead of order custom fields.

The Capture ID must be used as the `mgp-external-provider-reference` in the [custom fields](/connectors/mirakl/acquiring/echo/custom-fields#2-integrate-the-custom-order-fields-into-your-mirakl-api-calls).

This because the connector creates the Intent, captures it, and creates the Splits in a single sequence. Providing the Authorization ID or any other value not found in the settlement file will prevent Intents from being reconciled.

#### Hybrid flows: acquiring with Mangopay

In a hybrid setup, where your platform uses Mangopay as an acquirer as well as a third-party PSP, Intents are also created for orders processed with Mangopay.

In this scenario, `Mangopay` is used as the value for the Intent’s `ExternalData.ExternalProviderName`.

#### Mixed baskets: 1P and 3P in same order

The Mirakl Connector only creates intents for 3P orders. Platforms must integrate Echo directly for all 1P flows. This ensures that Intents can be created and updated by the connector and the platform for mixed baskets in order to have a full representation of paid orders.

### Reconciliation

Once Echo has reconciled the Intents and the settlement data [sent by your platform](#send-settlement-files-to-mangopay), the Split `Status` changes from `CREATED` to `PENDING_FUNDS_RECEPTION`.

For details on how Echo performs reconciliation, see the [Echo guide](/guides/echo#c-line-matching).

Once the settlement funds are received on your dedicated technical settlement wallet, the Split status becomes `AVAILABLE` and the Mirakl Connector executes the Splits. At this stage the funds move from the technical wallet to the seller wallet.

## Order Refunds to Intent Refunds

When a refund occurs, the Mirakl Connector retrieves refund details from Mirakl Orders to subsequently create the Intent Refund.

The `ExternalProvider` data for the Intent Refund is retrieved from the  `TransactionDetails` object in Mirakl Transaction Lines (using TL02).

If the wallet has sufficient funds, a Transfer Refund is performed sending the corresponding amounts back to the technical wallet.

<div className="block dark:hidden">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFFFFF',
        'primaryTextColor': '#2D0F37',
        'primaryBorderColor': '#2D0F37',
        'lineColor': '#2D0F37',
        'secondaryColor': '#FFFFFF',
        'tertiaryColor': '#FFFFFF',
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#E0DBE1",
        'noteBkgColor': "#E0DBE1",
        'noteTextColor': '#2D0F37'
      }
    }
  }%%
  sequenceDiagram
  participant Platform
  participant Mirakl
  participant MiraklConnector as Mirakl Connector
  participant Echo

  Platform->>Mirakl: Create Refund (OR28)
  Platform->>Mirakl: Mark Refund as paid (PA02)
  Platform-->>Mirakl: (optional) Add refund details (OR31)
  MiraklConnector->>Mirakl: Get refund details (TL02)
  MiraklConnector->>Echo: Create Intent Refund
  ```
</div>

<div className="hidden dark:block">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': "#090D0D",
        'primaryTextColor': "#FFFFFF",
        'primaryBorderColor': "#FFFFFF",
        'lineColor': "#FFFFFF",
        'secondaryColor': "#090D0D",
        'tertiaryColor': "#090D0D",
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#12282F",
        'noteBkgColor': "#090D0D",
        'noteTextColor': "#FFFFFF"
      }
    }
  }%%
  sequenceDiagram
  participant Platform
  participant Mirakl
  participant MiraklConnector as Mirakl Connector
  participant Echo

  Platform->>Mirakl: Create Refund (OR28)
  Platform->>Mirakl: Mark Refund as paid (PA02)
  Platform-->>Mirakl: (optional) Add refund details (OR31)
  MiraklConnector->>Mirakl: Get refund details (TL02)
  MiraklConnector->>Echo: Create Intent Refund
  ```
</div>

## Invoices to payouts

After the billing cycle, the Mirakl Connector checks that all payable orders are successfully reconciled by Echo.

It then adjusts wallet balances to account for transactions not visible to Echo (manual invoices, credit notes, subscriptions etc). Adjustments are visible in Adjustment reports.

The Mirakl Connector then proceeds with initiating the payout.

<div className="block dark:hidden">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFFFFF',
        'primaryTextColor': '#2D0F37',
        'primaryBorderColor': '#2D0F37',
        'lineColor': '#2D0F37',
        'secondaryColor': '#FFFFFF',
        'tertiaryColor': '#FFFFFF',
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#E0DBE1",
        'noteBkgColor': "#E0DBE1",
        'noteTextColor': '#2D0F37'
      }
    }
  }%%
  sequenceDiagram
      participant Mirakl
      participant MiraklConnector as Mirakl Connector
      participant MangopayAPI as Mangopay API

      MiraklConnector->>Mirakl: Get Invoices (IV01) each billing cycle

      %% Order Reconciliation
      rect rgb(230,230,250)
      Note over MiraklConnector: Order reconciliation
      MiraklConnector->>Mirakl: Check payable Orders (TL02)
      MiraklConnector->>Mirakl: Check Intents created
      MiraklConnector->>Mirakl: Check Intents reconciled with Splits available
      end

      %% Adjustments
      rect rgb(240,255,240)
      Note over MiraklConnector: Adjustments
      MiraklConnector->>Mirakl: Check adjustments (TL02)
      MiraklConnector->>MangopayAPI: Create adjustment transfers (with retries)
      end

      %% Payouts
      rect rgb(255,248,220)
      Note over MiraklConnector: Payouts
      MiraklConnector->>MangopayAPI: Create Payouts
      end
  ```
</div>

<div className="hidden dark:block">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': "#090D0D",
        'primaryTextColor': "#FFFFFF",
        'primaryBorderColor': "#FFFFFF",
        'lineColor': "#FFFFFF",
        'secondaryColor': "#090D0D",
        'tertiaryColor': "#090D0D",
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#12282F",
        'noteBkgColor': "#090D0D",
        'noteTextColor': "#FFFFFF"
      }
    }
  }%%
  sequenceDiagram
      participant Mirakl
      participant MiraklConnector as Mirakl Connector
      participant MangopayAPI as Mangopay API

      MiraklConnector->>Mirakl: Get Invoices (IV01) each billing cycle

      %% Order Reconciliation
      rect rgb(18 40 47)
      Note over MiraklConnector: Order reconciliation
      MiraklConnector->>Mirakl: Check payable Orders (TL02)
      MiraklConnector->>Mirakl: Check created Intents
      MiraklConnector->>Mirakl: Check reconciled Intents (that have Splits available)
      end

      %% Adjustments
      rect rgb(34 37 37)
      Note over MiraklConnector: Adjustments
      MiraklConnector->>Mirakl: Check adjustments (TL02)
      MiraklConnector->>MangopayAPI: Create adjustment transfers (with retries)
      end

      %% Payouts
      rect rgb(18 40 47)
      Note over MiraklConnector: Payouts
      MiraklConnector->>MangopayAPI: Create Payouts
      end

  ```
</div>

## Existing platforms

Mangopay has integrated Echo into the Mirakl Connector for existing platforms. If your platform has already integrated the Mirakl Connector, the table below gives an overview of the changes:

<table class="header-column">
  <thead>
    <tr>
      <th class="header" />

      <th class="header">Before Echo</th>
      <th class="header">With Echo</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <th class="header">Custom fields sent on Mirakl Orders</th>
      <td class="table-content">Not required</td>
      <td class="table-content">Creation and integration required by your platform</td>
    </tr>

    <tr>
      <th class="header">Settlement files from your third-party PSP sent to Mangopay</th>
      <td class="table-content">Not required</td>
      <td class="table-content">Integration required by your platform</td>
    </tr>

    <tr>
      <th class="header">Settlement payment types</th>
      <td class="table-content">Bank wire or vIBAN</td>
      <td class="table-content">vIBAN only (1 wallet per external PSP)</td>
    </tr>

    <tr>
      <th class="header">Trigger to move funds</th>
      <td class="table-content">Invoice generation by Mirakl</td>
      <td class="table-content">Split reconciliation by Echo</td>
    </tr>

    <tr>
      <th class="header">Frequency of fund movements</th>
      <td class="table-content">Once per billing cycle</td>
      <td class="table-content">Every day</td>
    </tr>

    <tr>
      <th class="header">Invoice reconciliation checks</th>
      <td class="table-content">None</td>
      <td class="table-content">Automated</td>
    </tr>

    <tr>
      <th class="header">Adjustments</th>
      <td class="table-content">None</td>
      <td class="table-content">For each group of transactions not related to orders (e.g. credit note, manual invoices, subscriptions)</td>
    </tr>
  </tbody>
</table>

### Activation - Existing platforms

For existing platforms already working with the Mirakl Connector, the steps are as follows:

<Steps>
  <Step title="Complete integration">
    You need to prepare the [integration above](#integration), including the 1P part if applicable.
  </Step>

  <Step title="Determine a go-live date with Mangopay">
    Once your integration is ready, you need to determine a go-live date.

    All orders from that date onwards will have Intents created for them. We recommend go-live to be the first day of a new Mirakl billing cycle.

    Contact Mangopay <a href="https://hub.mangopay.com/" target="_blank">via the Dashboard</a> to set up your go-live date.
  </Step>
</Steps>

For existing platforms, the go-live date begins a period of observability to ensure everything is running as expected before full activation.

The differences are shown below:

<table>
  <thead>
    <tr>
      <th class="header">Observability ON</th>
      <th class="header">Observability OFF</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">Intents are created and captured</td>
      <td class="table-content">Intents are created and captured</td>
    </tr>

    <tr>
      <td class="table-content">Splits are created but not executed on reconciliation</td>
      <td class="table-content">Splits are created and executed on reconciliation</td>
    </tr>

    <tr>
      <td class="table-content">The seller wallet is funded on invoice processing</td>
      <td class="table-content">The seller wallet is funded gradually</td>
    </tr>

    <tr>
      <td class="table-content">No adjustments are created</td>
      <td class="table-content">Adjustments are created</td>
    </tr>

    <tr>
      <td class="table-content">Payouts don’t depend on successful reconciliation</td>
      <td class="table-content">Payouts depend on successful reconciliation</td>
    </tr>
  </tbody>
</table>