Skip to main content
Mangopay Echo’s reconciliation process is described below, beginning with intents.

​
A. Declaration and capture

Your platform declares transactions as Intents, identified with the ExternalProviderReference. Once created, an Intents’ Status value is AUTHORIZED before being declared as CAPTURED. These Intents are not yet reconciled and the corresponding funds have not been received.

​
B. Settlement file processing

When a settlement file is uploaded successfully to Mangopay, the Echo system starts to parse the file. Echo first validates the file (format, single currency, etc). If validation fails, the Settlement Status changes to FAILED and the process stops for that file. If validation is successful, the Status becomes CREATED.

​
C. Line matching

Once the file is validated, Echo proceeds to reconciliation. Echo iterates through each transaction line of the file and attempts to match the ExternalProviderReference to a corresponding unreconciled Intent declared previously.

​
Fully successful matching

If a match is found for all lines, the Settlement Status changes to PENDING_FUNDS_RECEPTION. At the same time, the associated Intent is updated:
  • The SettlementId is linked in the Intent
  • The Status of the Intent’s Capture becomes SETTLED_NOT_PAID
  • The Status of any created Splits becomes PENDING_FUNDS_RECEPTION.

​
Unsuccessful matching attempts

If a match is found for some lines of the file, the Settlement Status changes to PARTIALLY_MATCHED. If no lines could be matched, the status becomes UNMATCHED. In both PARTIALLY_MATCHED and UNMATCHED cases, no part of the Settlement is settled using any funds that may arrive on the Virtual Account. These Settlements need to be re-uploaded so that they can be fully matched, using the POST Update a Settlement and generate a new upload URL endpoint.

​
D. Funds reception

The final step is that Mangopay receives funds from your platform’s partner PSP to a dedicated Virtual Account and associated wallet. When the system receives unallocated funds, it checks the amount with the oldest matched Settlement’s ActualSettlementAmount. If the funds received are sufficient:
  • The Settlement’s Status becomes RECONCILED
  • The Intent’s Capture’s Status becomes PAID
  • The AvailableAmountToSplit is populated with the received amount
  • The Intent’s Splits become AVAILABLE
If the funds are not sufficient, the Settlement’s Status becomes INSUFFICIENT_FUNDS. These settlements remain unmatched and are retried when additional funds are received on the dedicated Virtual Account’s wallet. So, when funds arrive on the virtual account, the system looks for the oldest Settlement that has a Status of PENDING_FUNDS_RECEPTION or INSUFFICIENT_FUNDS and settles it first, passing the object to RECONCILED.

​
Settlement file state machine

The overall state machine for a Settlement object is below: