Echo integration

​

Overview diagram

The diagram below shows an overview of how the Echo solution works: The rest of this guide refers to the numbers in the diagram above, 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

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.

​

Postman

Once onboarded, you can use the Mangopay API Postman to start testing, where there is a dedicated folder for theEcho solution. See the 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

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

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

​

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 1P 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

​

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, 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 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, 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 LineItemsobject – 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

​

Intent Capture

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

POST Create an 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

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 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 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 endpoint. You need to track the outcome of the dispute using the PUT Update an 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

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

​

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

​

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.

​

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 that your platform can use to be notified about activity related to Intents, Settlements, and Splits.