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: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 IntentInclude 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.
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’sSeller
: 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’sSeller
: 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’sId
:
POST Create a Capture of an IntentIn 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 IntentCancellations 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
Note – Split creation timing depends on your workflowA Split can be declared via the API as soon as the Intent
Status
is CAPTURED
or PARTIALLY_CAPTURED
(2B).However, depending on your workflow, it may be more suitable to wait until a later stage, such as the settlement to Mangopay being reconciled (5C) or paid (6A & 6B).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
Applies to: Any platform using a third-party PSP for funds acquisition, whether the platform uses the Mirakl Connector or not.For Mirakl Connector platforms, the payment intent declarations are created automatically by the connector, but the settlement data must be provided by the platform.
POST Create a SettlementYou 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 SettlementStatus
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 theFeesAmount
parameter.
Once the funds are credited to the sellers’ wallets, they can be paid out to their external bank accounts.
Echo endpoints
Intent endpoints
POST Create an Intent
Declare a transaction authorization processed by a third-party PSP
GET View an Intent
Retrieve the declaration of a transaction processed by a third-party PSP
POST Create a Capture of an Intent
Declare the full or partial capture of an authorization processed by a third-party PSP
Intent Split endpoints
POST Create a Split of an Intent
Create a transfer to the wallet of the seller of an Intent line item
POST Execute a Split of an Intent
Release the funds of a Split to the wallet of the seller of the Intent line item
POST Reverse a Split of an Intent
Reallocate a Split’s funds back to the Escrow Wallet if not yet executed
PUT Update a Split of an Intent
Modify a Split before execution
GET View a Split of an Intent
Retrieve details of a Split of an Intent
Settlement endpoints
POST Create a Settlement
Upload a Mangopay-format settlement file for a single currency to be reconciled with Intents
PUT Update a Settlement
Upload an additional file to update the Settlement
GET View a Settlement
Retrieve the Settlement details generated from file upload
Echo reports
Mangopay provides reports to allow you to download data related to Intents, Settlements and Splits in CSV format. You can generate these via the API or via the Dashboard (which also handles automated scheduling). There are 4 reports relevant to Echo, each with different available data columns and filters (see the reports guide for details):- Intent – Summary of all intents declared during the selected period, detailing the total funds expected to enter the platform’s escrow wallets.
- Intent action – Summary of all operations related to intents processed during the selected period, detailing the expected money movements to be escrowed — including payments, refunds, refund reversals, and chargebacks.
- Settlement – Summary of all settlement files uploaded during the selected period to initiate the reconciliation process, confirming the expected money movements to be escrowed.
- Split – Summary of all splits related to intents during the selected period, detailing the transfer of funds to the declared destination.