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, 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 →

​

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 →

​

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 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.

​

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.

​

Creating Intents

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, representing the payment authorization. They are created when the Mirakl Transaction Lines are payable.

​

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, if you use multiple captures per logistic_order, use order line custom fields (order_line_additional_fields) instead of order custom fields.

​

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, the Split Status changes from CREATED to PENDING_FUNDS_RECEPTION. For details on how Echo performs reconciliation, see the Echo guide. 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.

​

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.

​

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:

	Before Echo	With Echo
Custom fields sent on Mirakl Orders	Not required	Creation and integration required by your platform
Settlement files from your third-party PSP sent to Mangopay	Not required	Integration required by your platform
Settlement payment types	Bank wire or vIBAN	vIBAN only (1 wallet per external PSP)
Trigger to move funds	Invoice generation by Mirakl	Split reconciliation by Echo
Frequency of fund movements	Once per billing cycle	Every day
Invoice reconciliation checks	None	Automated
Adjustments	None	For each group of transactions not related to orders (e.g. credit note, manual invoices, subscriptions)

​

Activation - Existing platforms

For existing platforms already working with the Mirakl Connector, the steps are as follows: 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:

Observability ON	Observability OFF
Intents are created and captured	Intents are created and captured
Splits are created but not executed on reconciliation	Splits are created and executed on reconciliation
The seller wallet is funded on invoice processing	The seller wallet is funded gradually
No adjustments are created	Adjustments are created
Payouts don’t depend on successful reconciliation	Payouts depend on successful reconciliation