Draft from the article outline in the copy deck. Full text of 1,200 to 1,800 words to follow after owner review.
The requirement: every dollar visible at every step
A cross-border payout passes through several hands before the contractor is paid. The ledger has to show, at any moment, where each amount sits and in which currency, so that finance can answer "where is this money" without opening partner portals.
Account structure
We use customer accounts, a clearing account for each step (on-ramp, in transit, off-ramp), fee accounts, an FX account and a suspense account. Funds in conversion sit in a named clearing account rather than disappearing between two systems.
Entries for one payout, step by step
Each state change in the payout writes a balanced pair of entries: funding moves value from the customer account to on-ramp clearing, conversion moves it to in-transit clearing, delivery moves it to off-ramp clearing and then out. [OWNER: add the entry table from the repo]
Recording FX
Every conversion records the rate source, the timestamp and an explicit FX leg, so a USD amount and its CAD result are linked by an entry rather than by a calculation done later.
Invariants we test
Entries always balance; customer balances never go negative; clearing accounts return to zero once a payout completes or is resolved. These run as automated tests on every change to the ledger code.
Idempotency and retries
Every write carries an idempotency key, so a retried request records nothing twice and a payout cannot be paid twice.
What we would change
[OWNER: one or two honest notes on what the team would design differently]
Sources
[Sources list with links and Last checked dates to be added before publishing]
Related engagement: Payments Strategy Sprint.
Munro Banting advises, designs and builds. Client funds are held and moved only by licensed partners. Munro Banting does not hold, transmit or exchange client funds.