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

Mangopay Echo is a unified solution for platforms to declare payments not acquired by Mangopay but which then transit the Mangopay environment as part of the workflow. This allows payments to be correctly reconciled against the funds that are received on the platform’s escrow wallet.

​

Flow types

Mangopay Echo is applicable to platforms acquiring funds for goods or services sold by your platform directly (first-party or 1P transactions), as well as for goods or services sold by third-party sellers on your platform (third-party or 3P transactions).

​

Echo for Mirakl Connector platforms

Some platforms acquiring with a third-party PSP are also using Mangopay’s Mirakl Connector to synchronize their sellers and payouts.

Mangopay’s Mirakl Connector handles the integration of Echo for your 3P payments, which is made possible by your integration of Mirakl Custom Fields on your Mirakl API calls. For more details on this setup process, see the dedicated Echo guide for Mirakl Connector platforms.

Mirakl Connector platforms also need to send settlement files to Mangopay, as described below.

Furthermore, if your platform is using the Mirakl Connector and also selling goods or services directly as 1P payments, you need to integrate Echo Intents and captures for these transactions, because they are not reflected in the Mirakl Connector.

​

Overview diagram

The diagram below shows an overview of how the solution works:

The rest of this guide refers to the numbers in the diagram above, along the main stages.

​

Declare payment authorization

Mangopay Echo allows your platform to compliantly declare transactions acquired by third-party PSPs as Intents. The Intent API object represents a payment authorization processed by a third-party PSP, and can subsequently be used to track the full lifecycle of the transaction.

​

Intent

The Intent represents the successful authorization of the transaction (1A), while its capture represents the acquisition of the funds by the PSP.

To create an Intent (1B), call the endpoint:

POST Create an Intent

Include the following information:

• Payment details – Amount, currency, payment method
• External provider – Provider name, unique identifier of the transaction, date
• Buyer (optional) – If the user is also registered with Mangopay, the Mangopay UserId that made the payment
• Line items – A list of items purchased by the buyer. Each line item identifies the seller (Mangopay user and wallet) and the item purchased (amount, SKU, etc.). Future actions declared for the intent It also tracks the amount of the line item that is subsequently captured, refunded, disputed, and so on.

The seller details of a line item are different depending on whether the transaction is 1P or 3P.

​

First-party transactions (1P)

First-party (1P) flows refer to transactions where your platform sells directly to the user on your website: an e-commerce transaction. In a 1P scenario, your platform operator is the beneficiary of the transaction.

For a 1P Line Item, your platform is the line item’s Seller: your ClientId is the AuthorId, and your Fees Wallet is the WalletId.

​

Third-party transactions (3P)

Third-party flows refer to transactions where your platform acts as an intermediary between the buyer and a seller. In a 3P scenario, the Seller is the beneficiary.

For a 3P line item, The seller on your platform is the line item’s Seller: their UserId is the AuthorId and their wallet is the WalletId.

​

Declare capture or cancel

When the third-party PSP captures the funds (2A), you need to declare this to Mangopay (2B).

​

Intent Capture

To declare the capture, call the endpoint using the Intent’s Id:

POST Create a Capture of an Intent

In all cases, the capture of an Intent is a separate Mangopay API call from the Intent creation.

There are three possible scenarios:

• Authorization simultaneous with capture – No new data required because the external data is the same as the authorization, so the call has an empty body.
• Authorization and delayed full capture (e.g. preauthorization) – New data is required for the external PSP reference and amount, because a delayed capture is necessarily a different object.
• Authorization and partial captures – New external data is required along with the amount for each line item that is being captured.

​

Intent Cancel

If an payment authorization (or part of it) is not used, then the Intent can be fully or partially cancelled. To do so, call the endpoint:

POST Create a Cancel of an Intent

Cancellations can be partial. In a cancellation scenario, new external data is necessarily required as the action must require a new object with the third-party PSP.

​

Declare future split transfer to seller

In Echo, the future transfer of funds to seller’s Mangopay wallet is called a Split, and you need to create this request in the Mangopay API.

To create a Split (3), call the endpoint:

POST Create a Split of an Intent

When you create a Split for the Intent, you declare also the fees that will be taken by your platform for the transaction (and diverted to your Fees Wallet) when the split is executed by Mangopay (7B).

However, you can also specify the PlatformFeesAmount in the Intent, which is used if there is no FeesAmount in the Split.

​

Track the payment lifecycle

Once the authorization and capture are declared, your platform needs to track any other transaction events that occur on the payment (4A & 4B). Besides a cancellation or partial cancel (mentioned above), there are two other possible pathways for the payment.

​

Intent Refund

The payment can be refunded by the seller, and this needs to be reflected in an Intent Refund. Intent Refunds can be full or partial.

For some payment methods, particularly those involving bank wire transfers, it can happen that a refund cannot be processed. In the Echo solution, this is a reflected in a refund being reversed, indicating that the funds were returned to the platform.

​

Intent Dispute

The payment can be subject to a chargeback or dispute initiated by the buyer. Your platform needs to track this eventuality in an Intent Dispute, which can be won or lost. If your provider returns the funds to you temporarily while it is defended, you can reflect this status change in the Intent Dispute, but there is no movement of funds on Echo’s side until the outcome of the dispute.

​

Send settlement files to Mangopay

When your third-party PSP settles the transaction with your platform, they provide settlement files for reconciliation purposes (5A).

Mangopay Echo needs settlement data to be able to reconcile the funds entering the Mangopay environment with the payment Intents that your platform previously declared. The payment and possible refund or dispute may all be reflected in the settlement of the transaction to your platform.

You need to format this settlement data according to Mangopay’s expected format and send settlement files to Mangopay as soon as they become available, and in one file for each currency (5B).

To do so, create a CSV file according to Mangopay’s settlement file format with the data received from your provider. Then send it via the endpoint:

POST Create a Settlement

You can use this example template to help you.

In response, the API creates the Settlement object with SettlementId and other summary data about the status and amounts.

​

Fund the escrow wallet

In your workflow, the funds acquired by your third-party PSP arrive in the Mangopay environment as a payment to your dedicated Escrow Wallet (6A).

In most cases, this payment is handled by your PSP. In some cases, your platform makes the payment.

Once the funds arrive, the Settlement Status changes to RECONCILED. If the funds which arrive on the wallet do not cover the amount declared in Intents and Settlements, the Status changes to INSUFFICIENT_FUNDS.

​

Release split transfers to sellers

Once the Settlement is reconciled, your platform can release the previously created Splits to the sellers (7A).

Your platform can divert fees to your Fees Wallet using the FeesAmount parameter.

Once the funds are credited to the sellers’ wallets, they can be paid out to their external bank accounts.

​

Echo endpoints

​

Intent endpoints

​

Intent Split endpoints

​

Settlement endpoints