Best practices for sending money back out to the world vs keeping them in a separate reserved ledger account

[gurtajkhatra]

I've been reading up on some of the Formance account modeling patterns here: https://docs.formance.com/modules/ledger/tutorial

I noticed that in the rideshare example the funds move from driver:zz:main back out to the world when the driver gets paid out - this makes sense since the money is leaving the system.

What is the proper way of modeling the reversal of this flow when it comes to things like refunds? Is it best practice to bring money back in from the world? Alternatively is it recommended to just revert the transaction?

Thanks

[formance-support[bot]]

Hi,

In short, you should model refunds as new counter transactions rather than using the reversal endpoint.

A refund is its own business event with its own PSP reference, its own timing, often a partial amount, and sometimes its own fee semantics (refund fees, fee reversals, etc.). Capturing it as a fresh transaction preserves all of that context, whereas reverting collapses it into an undo of the original.

For the rideshare flow specifically, modelling the refund as a new transaction that brings the relevant postings back from world (or the appropriate external/PSP-side account) into the corresponding internal accounts is the right approach. The ledger should reflect that the refund is a distinct event in your system.

As for the reversal endpoint, it's better suited to cases where you genuinely want to undo a prior booking rather than represent a new business event. Broadly, that splits into:

• Error fixing — a transaction was booked that shouldn't have been (e.g. a duplicate, a wrong amount, a script bug).
• Technical reasons — something didn't behave as expected and you need to roll it back to a known state.
• Business reasons — these are usually better handled by a counter transaction with its own timeline, reason, and identifiers, rather than a revert.

So the choice between "counter transaction" vs. "reversal" really depends on whether the event you're recording is a new fact about your business (counter transaction) or a correction to a prior booking (reversal).

I hope this helps.