Skip to main content
A hybrid flow is one where your platform acquires funds using both a third-party PSP and Mangopay. This setup is common for platforms that want a multi-acquirer configuration. It gives you flexibility in payment methods and settlement timing that you may not get if you rely on a single acquirer.

​
Note on Mirakl Connector compatibility

Hybrid processing is compatible with the Mirakl Connector. The integration approach mirrors the standard Mirakl Echo integration — Mirakl orders generate Intents — except that you set mgp-external-provider-name to Mangopay in the Mirakl custom fields for Mangopay-acquired orders. The two implementation approaches described below are available to Mirakl Connector platforms.

​
Mangopay pay-ins and Echo

When Mangopay is processing pay-ins, your platform has more flexibility in how you manage the Mangopay part of the flow, because Mangopay has full visibility of the funds. Because Mangopay has visibility on these flows, there is not the same strict regulatory obligation to use Echo for Mangopay-acquired pay-ins. However, routing these transactions through Echo still has benefits:
  • Uniform integration — The same Intent-based workflow applies regardless of which PSP processed the payment.
  • Centralized reporting — All pay-ins pass through Echo, giving you standardized visibility across your full pay-in flow.
  • Consistent refund and dispute handling — Refunds and chargebacks can be managed in the same way across acquirers.
Echo is required in some hybrid scenarios — for example, when a single order uses mixed payment methods, such as a Mangopay wallet balance combined with a payment via a third-party PSP. If you are unsure whether Echo is required or beneficial for your hybrid setup, contact Mangopay via the Dashboard.

​
Hybrid models

There are two approaches to managing hybrid flows through Echo:
ApproachStandard hybridAdapted hybrid
SummaryTreat Mangopay like a third-party acquirer. Transfer funds to the Escrow Wallet, then reconcile via settlement file.Funds move directly from the payer wallet to the seller wallet. Echo monitors the Mangopay pay-in status.
Settlement fileRequiredNot required
The best approach depends on your user model and timing between payment and service delivery:
ApproachStandard hybridAdapted hybrid
Buyer statusIf buyers are KYC-verified OWNER users, the standard approach may suit you better, because you will likely prefer to transfer funds from the buyer wallet to the Escrow Wallet before paying the seller.If buyers are PAYER users, the adapted approach may be preferable because funds move directly to the seller.
Payment timingIf there is a delay between order payment and service delivery, the standard approach lets you hold funds in the technical wallet until the seller is paid.If the seller is paid at the point of interaction, the adapted approach is simpler as funds move directly from the buyer to the seller.

​
Standard hybrid integration

The standard approach works like a third-party PSP integration, with a few Mangopay-specific differences. Your platform needs to:
  1. Transfer funds to the Escrow Wallet when a purchase is authorized or captured
  2. Generate and upload a settlement file that has the Transfer Id value in ExternalProviderReference. This triggers the process to reconcile the settlement, mark Intents as PAID, and make funds available for Splits
  3. Orchestrate refunds and disputes in Mangopay, both via Echo and back to the buyer’s payment method
  4. Cover funds in cases where sellers have already been paid out and you need to refund the buyer
Each step is described in detail below:
1

Transfer pay-in funds to the Escrow Wallet

When you process a pay-in with Mangopay under the standard hybrid approach, call the POST Create an Intent endpoint for each transaction. The Intent Status becomes AUTHORIZED.When the funds arrive in Mangopay’s ecosystem and the pay-in Status becomes SUCCEEDED, capture the funds in two steps:
  1. Call the POST Create a Transfer endpoint to transfer the funds from the buyer wallet to your Escrow Wallet
  2. Once the Transfer Status is SUCCEEDED, call POST Create an Intent Capture on the Intent, using the Transfer Id as ExternalProviderReference and Mangopay as ExternalProviderName
2

Generate and upload a settlement file

Build a settlement file for reconciliation according to Mangopay’s settlement file format. In each line, set ExternalProviderReference to the Id of the Mangopay Transfer.Once uploaded, Echo reconciles the settlement file against the declared Intents. Matching Intents transition to PAID and the funds become available for Split execution. See the Echo reconciliation guide for details on this process.
3

Orchestrate refunds and disputes

Refunds and chargebacks for Mangopay-acquired pay-ins are processed within Mangopay. Your platform needs to orchestrate these operations end to end.When you receive a refund request for a Mangopay pay-in:The steps required depend on where the funds are in the flow at the time of the refund.You must always declare the Intent Refund to Echo by calling the POST Create an Intent Refund endpoint.You must also include the refund in a settlement file. When you upload the file, Echo matches the refund line to the Intent Refund and attempts to refund any Splits that have already been executed.For Splits that are already executed, meaning the funds already moved to the seller wallet, there are two possible scenarios:
  • Funds available in the seller wallet — The Split Refund succeeds. You can reverse the original Transfer to the Escrow Wallet and refund the buyer.
  • Funds not available in the seller wallet — The Split Refund fails. You must fund the operation from your platform wallet. Echo does not retry failed Split Refunds.
4

Cover fund if sellers already paid out

If funds have already been paid out to sellers and cannot be returned to the Escrow Wallet, your platform must cover the shortfall from your platform wallet so that future settlements are not delayed.Two approaches are commonly used:
  • Transaction by transaction — Cover each refund individually as it occurs
  • Float — Maintain additional funds on the Escrow Wallet to absorb timing differences between seller payouts and buyer refunds

​
Adapted hybrid approach

In the adapted hybrid approach, Echo monitors the Mangopay pay-in directly and the Splits debit the payer wallet without an intermediate Transfer to the Escrow Wallet.
1

Process the pay-in and declare the Intent

When a purchase is made, process a pay-in to Mangopay.Then call the POST Create an Intent endpoint with:
  • ExternalProviderReference — The Id of the pay-in
  • ExternalProviderName — Mangopay
  • LineItems.SplitOriginWalletId — The pay-in’s CreditedWalletId where the pay-in funds arrive
2

Capture the Intent

Call the POST Create an Intent Capture endpoint so Echo knows to monitor the transaction.
3

Echo monitors the pay-in

Echo monitors the pay-in until its Status becomes SUCCEEDED for the specified SplitOriginWalletId.When the pay-in succeeds, Echo transitions the Intent from CAPTURED to PAID and makes the funds available for Split.
4

Create and release the Split

Call the POST Create an Intent Split endpoint to create the Split (which can be done any time after the Intent is captured).When you execute the Split, funds move directly from the payer wallet to the seller wallet.

​
Reconciliation and settlement

Under the adapted approach, Mangopay transitions the Intent to PAID based on the pay-in status and makes funds available to Split immediately. No settlement file is required. Splits debit the SplitOriginWalletId directly — there is no Transfer to the Escrow Wallet.

​
Refunds and disputes

In the adapted approach, you need to declare refunds and disputes to Echo as Intent actions — for example, an Intent Refund or Intent Dispute. Echo then attempts to retrieve funds from the seller wallet by executing a Split Refund. You need to monitor the Split status:
  • Split Refund succeeds — If the split succeeds, refund the buyer’s payment method.
  • Split Refund fails — If the split fails, you need to fund the buyer’s wallet from your platform wallet to enable the refund to the buyer’s payment method. Then reclaim the funds from the seller at a later time.