> ## 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. # Echo integration ## Overview diagram The diagram below focuses on the Intents and the actions performed by your platform when using Echo. This integration guide follows refers to the numbered steps along the main stages. ## 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 * Whether your platform receives net or gross settlement from your PSP(s) 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 (sent by your PSP or your platform in step **6A**). The process above is the same for each `ClientId` you use, whether in Sandbox or Production. For existing clients, this process is taken care of by Mangopay. ### Testing To simulate the arrival of funds on the Virtual Account, you can use the Mangopay Dashboard. For details on how to do this, see the guide on [testing pay-ins to Virtual Accounts](/testing/payment-methods#virtual-accounts) **→** #### Postman Once onboarded, you can use the Mangopay API Postman to start testing, where there is a dedicated folder for the Echo solution. See the [Postman](/postman) guide for details on how to fork the collection and set up your environment with your `ClientId` and API key. ## 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**](/api-reference/intents/create-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 `LineItems` object identifies the seller and the item purchased (amount, SKU, etc.). ### Line items The `LineItems` object describes the sellers and items purchased from them in the transaction. Echo is designed to be flexible to accommodate a range of integration models, and this can have an impact on seller data in the `LineItems`. #### Third-party transactions (3P) Most commonly, the Intent is describing a transaction between a buyer and a seller on your platform. In this scenario, your platform is an intermediary between third-parties (the buyer and seller), so we can call it a third-party transaction (3P). In a 3P scenario, the Seller is the beneficiary. For a 3P line item, `LineItems.Seller` is the seller on your platform: * `LineItems.Seller.AuthorId` is the `UserId` of the seller on your platform * `LineItems.Seller.WalletId` is the `WalletId` of the seller on your platform #### First-party transactions (1P) Echo has also been designed to accommodate transactions where the platform is the seller, selling directly to the buyer – as in standard e-commerce transactions. In this case, we can refer to it as a first-party transaction (1P). In a 1P scenario, your platform operator is the beneficiary of the transaction. For a 1P line item, `LineItems.Seller` is your platform: * `LineItems.Seller.AuthorId` is your `ClientId` * `LineItems.Seller.WalletId` is your Fees Wallet `Id` in the relevant currency (e.g. in EUR, `FEES_EUR`) ### Add line items to an Intent It is possible to add one or more additional `LineItems` to an existing Intent. To date, this scenario is only typically encountered if your platform is using the Mirakl Connector, but as the functionality is technically available it is described here for completeness. When the Intent was created by the [Mirakl Connector](/guides/echo#echo-for-mirakl-connector-platforms), your platform needs to add the 1P part of a mixed basket to the Intent separately, as these funds are not visible to the connector. You can add line item by using the same `ExternalProviderReference` as the initially created Intent and on the same [POST Create an Intent](/api-reference/intents/create-intent) endpoint. To do so, send the `ExternalProviderReference` of the previously created Intent and include **only the new** `LineItems` object(s). Line items can be added to intents both before and after [capture](#intent-capture), as shown by the examples below. **Capture before additional line item:** 1. Create Intent with one `LineItems` object – Intent becomes `AUTHORIZED` 2. Capture `LineItems` object – Intent becomes `CAPTURED` 3. Add second `LineItems` object – Intent becomes `PARTIALLY_CAPTURED` 4. Capture second `LineItems`object – Intent becomes `CAPTURED` again **Capture after additional line item:** 1. Create Intent with one `LineItems` object – Intent becomes `AUTHORIZED` 2. Add second `LineItems` object – Intent remains `AUTHORIZED` 3. Capture first `LineItems` object – Intent becomes `PARTIALLY_CAPTURED` 4. Capture second `LineItems` object – Intent becomes `CAPTURED` ## Declare capture or cancel When the third-party PSP captures the funds (**2A**), you need to declare this to Mangopay (**2B**). Alternatively, if the Intent, or part of it was created in error, it can be canceled. This must be done before any of the Intent is captured. > [POST Cancel an Intent](/api-reference/intents/cancel-intent) ### Intent Capture To declare the capture, call the endpoint using the Intent’s `Id`: > [POST Create an Intent Capture](/api-reference/intents/create-intent-capture) 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. ## 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 an Intent Split](/api-reference/intents/create-intent-split) **Note – Split creation timing depends on your workflow** A 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**). 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. Call the [POST Create an Intent Refund](/api-reference/intents/create-intent-refund) endpoint to declare a full or partial refund. In this case the corresponding amount is not expected on the escrow wallet, and therefore when the refund transaction is declared in the Settlement, the amount must be negative. For some payment methods, particularly those involving bank wire transfers, it can happen that a refund cannot be processed and the funds are returned to your platform. In this scenario, you can track this event by reversing the previously declared refund. To do so, call the [POST Reverse an Intent Refund](/api-reference/intents/reverse-intent-refund) endpoint. Reversing a refund effectively changes the `Status` of the existing refund (and Intent) to `REFUND_REVERSED`; it does not create a new refund. ### 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 by calling the [POST Create an Intent Dispute](/api-reference/intents/create-intent-dispute) endpoint. You need to track the outcome of the dispute using the [PUT Update an Intent Dispute](/api-reference/intents/update-intent-dispute) endpoint: * `DISPUTE_WON` – The dispute was ruled in favor of your platform. The Settlement file includes the transaction with this status and the amount is positive, indicating that the funds are expected on the escrow wallet. * `DISPUTE_LOST` – The dispute was ruled against of your platform. The Settlement file includes the transaction with this status and the amount is negative, indicating that the funds are not expected on the escrow wallet. You can use the intermediary state, `DEFENDED`, if your PSP returns the funds to your platform while the outcome is being decided, but there is no movement of funds on Echo's side until the outcome of the dispute is known (and declared). ## 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. 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**). If the data provided does not match the Intents created, the reconciliation process fails and the settlement file `Status` becomes `FAILED` or `PARTIALLY_MATCHED`. In this case, you need to retrieve the errors using the [GET View validation errors for a Settlement](/api-reference/settlements/view-settlement-validations) endpoint and address them. ### Settlement file amount calculation The amounts that you declare in the settlement file need to be positive or negative depending on the `ExternalTransactionStatus`: * `SETTLED` - Positive * `REFUNDED` - Negative * `REFUND_REVERSED` - Positive * `DISPUTED` - Negative * `DEFENDED` - Negative * `DISPUTED_WON` - Positive * `DISPUTED_LOST` - Negative This positive and negative polarity is critical to ensure that the total amount of the Settlement file is calculated correctly. The formula used is given below: > TotalNetSettlementAmount = MAX(0, SUM(SETTLED) + SUM(REFUNDED) + SUM(DISPUTED) + SUM( REFUND\_REVERSED) + SUM(DISPUTED\_WON) + TotalSettlementFeesAmount) As shown (by the MAX formula), the amount cannot be negative. In such a case, for example if the total refunded amount equals more than the settled amount, then Mangopay does not return funds to the PSP. Rather, they are used towards the next Settlement. ### How to send a settlement file to Mangopay Using the data received from your provider, create a CSV file according to [Mangopay's settlement file format](/api-reference/settlements/settlement-file). You can use this [example template](/api-reference/settlements/settlement-file#example-template) to help you. Call the [POST Create a Settlement and secure URL for file upload](/api-reference/settlements/create-settlement) endpoint with the `FileName` that Mangopay will use for your file. This API call generates a unique temporary pre-signed URL that you can use to upload your file. Send your file to the URL returned, using the `text/csv` **Content-Type** (see [PUT Upload settlement file to secure URL](/api-reference/settlements/upload-settlement-file) for details). Once the file is uploaded, the Settlement object’s status changes from `PENDING_UPLOAD` to `UPLOADED` (which you can retrieve on [GET View a Settlement](/api-reference/settlements/view-settlement)). Echo then proceeds to parse the file as described below. ## Reconciliation Echo performs reconciliation between the settlement file you upload and the Intents declared by your platform. The reconciliation process is described in detail in the dedicated [Echo reconciliation guide](/guides/echo/reconciliation). ## 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 (referred to as direct settlement). 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. ## Webhooks There are dedicated webhook [event types](/webhooks/event-types#echo) that your platform can use to be notified about activity related to Intents, Settlements, and Splits.