For Partners: Merchant Reconciliation

The world of online payments is changing rapidly. Customers have increasing demands, want to receive money instantly, and automate more and more. Mollie is the frontrunner of these changes, and needs to keep up to ensure we can keep you, as a partner, empowered for all merchants. In doing so, we are changing and upgrading the core of Mollie so we are future proof for the years to come. 

In this regard,  the relation between settlements and invoices has changed.

A settlement no longer belongs to / falls under an invoice like it used to. In our old-style way of working our invoicing process would only invoice fees associated with one or more settlements. This would cause confusion if payments were processed, costs were made, but no settlement was received (a payout can be paused or blocked for numerous reasons). In this case, there would be no invoice for this period, although there would be costs.

This invoice process has been changed to only charge fees that have been charged within a monthly period (e.g. Jan 1st 00:00:00 (inclusive) -> Feb 1st 00:00:00 (exclusive) based on Europe/Amsterdam time). So, it will be disconnected from settlements. Because of this fundamental change, the relationship has also changed and the Settlements API has been adapted. 


Overview of changes

This section describes the relevant changes that have come about and should be taken into account.

New “invoiceId” field per period.

To correlate the withheld transaction fees to the respective invoices partners can now use the “invoiceId” property in the Get Settlement API response.

For old-style settlements there is a top-level “invoiceId” property. All costs reported by this settlement, regardless of the periods, belong to the invoice that will eventually be linked in this singular property. In the above mentioned example, the third settlement would contain revenue and costs for two periods, but they correlate to one invoice.

For new-style settlements there is still this top-level “invoiceId” property, but it is not the only invoice relevant to the costs reported by this settlement. Instead, the costs reported in the settlement belong to a different invoice based on the period that they are in. In the above mentioned example (right-side), the third settlement would have two periods (with revenue and costs) and the costs would correlate to two different invoices.

Because of this, the Settlement API was updated to include an “invoiceId” property contained in each separate period reported by the settlement. The top-level “invoiceId” property (as well as the invoice in the “links”) property will be filled with the oldest invoice that is related to this settlement (oldest period).

Textual descriptions in the Settlements API might differ

For the new-style settlements, the “description” and “method” fields can return different values than they used to return. This has to do with increased granularity of the reporting or because of textual descriptions that were lacking in clarity or translation that have been improved.

Fixed and variable costs are no longer split

In the Settlements API, each element under “costs” has a pricing property associated with it that specifies the fixed and variable fee. It used to be the case that whenever Mollie withheld funds to prepay a fee with a fixed and variable component, it would show these using 2 separate cost elements. One of these will contain only the fixed fee (with the variable pricing set to 0) and one will contain only the variable fee (with the fixed pricing set to 0).

For the new-style settlements, such fees with both a fixed and variable component will simply show up as a single line with the fixed pricing and variable pricing mentioned.

Added: the Invoice Compensation

With our new balance system, payments are settled to the balance in real-time and we immediately deduct the fees from the settlement (i.e. a prepayment of the fee). Because of this, the amount we deduct has to be a rounded real amount.

At the end of the month, when the merchant is invoiced, these individual roundings might not align with the total of the invoice, which might’ve been rounded differently in the end due to summation or VAT calculation.

When this happens, the merchant will have prepaid more than the invoice total. But do not worry, we will transfer this amount directly back to the balance of the merchant. This will happen under the name of an Invoice Compensation. The amount due on the invoice will therefore render zero. 

This invoice compensation is needed to properly match the total of the invoice in the bookkeeping. It can be found in our interface, Settlements API, or Exports (MT940 / CODA).


  • Exports: The invoice compensation for an invoice over January’s period will show up in the next period, since that is when the invoice is created and the money is deposited on the merchant’s balance.
  • Settlements API: The invoice compensation for an invoice over January will show up in the period January, as it should be linked to the invoiceId that is returned for that period.


Can't find what you're looking for?

Please contact our support, for help.