Skip to content
allanninal.dev/build
Collaborate

Part 3 of 7 · Payout reconciler series ~5 min read

A clearing account for every provider

Most ledgers that record card takings have one account for it, if they have one at all, and its balance is whatever it happens to be. The design here turns that balance into a claim: this provider owes us this much today. A claim can be checked.

Key takeaways

  • Sales, refunds, disputes and fees post to clearing. Payouts move money from clearing to the bank.
  • What is left is what that provider owes you, and it has a named debtor.
  • The provider reports its own balance, so the figure can be checked every day.
  • Drift means a line missing or counted twice, most often from a report nobody parsed.
  • At year end the balance is an asset: in transit, unwithdrawn, or held in reserve.

Posting through clearing

Settlement lines and a payout posted through a provider clearing accountA vertical chain inside an AWS account container, entered from a box on the left labelled A settled batch, lines that sum to their payout. Post the activity: sales up, and refunds, fees and disputes down. Post the holds: reserve held and released, as lines. Post the payout: from clearing to the bank. Compare balances: ours against the provider's own, with a side exit labelled differs leading to Find the gap, a line missing or counted twice. The final step is Carry the balance: what this provider owes, and why. A note says nothing posts to sales from the bank any more, because the bank only ever receives transfers out of a clearing account, which is what a payout actually is.AWS ACCOUNTA settled batchlines that sum totheir payoutPost the activitysales up; refunds,fees, disputes downPost the holdsreserve held andreleased, as linesPost the payoutfrom clearingto the bankCompare balancesours against theprovider's ownFind the gapa line missingor counted twicediffersCarry the balancewhat this providerowes, and whyNothing posts to sales from the bank any more. The bank only ever receives transfers out of a clearing account, which is what a payout actually is.
Fig 1. Three postings and one comparison. The comparison is only possible because each provider has an account of its own.
  • Machine learning
  • Security & identity
  • Management
  • Analytics

Why one per provider

A single account called card receipts can hold the right total and be wrong in every part. If one provider owes four hundred pounds more than the ledger thinks and another four hundred pounds less, the combined account balances perfectly and both errors are invisible.

Separate accounts also match how the money behaves. Each provider has its own payout schedule, its own reserve policy and its own way of charging for disputes, and each publishes its own balance. An account per provider is the only shape in which that published balance has something to be compared with. Where a provider holds more than one currency, or the business has two accounts with it, that is two clearing accounts.

The drift that found the wrong report

In the first month the system ran, the checkout provider’s clearing account showed £346.20 more than the provider said it owed. Every payout that month had passed the penny rule, so nothing inside the parsed reports was wrong. The difference had to be something the parser had not seen yet.

It was a lost dispute. The customer’s bank had taken back £331.20 and the provider had charged a £15.00 dispute fee. Both had already come off the provider’s balance, but the parser was reading the export grouped by payout, which lists a line only once it belongs to one, and the next payout was nine days away. Nothing was lost; that payout would have carried both lines. But for nine days the ledger believed the provider owed £346.20 it did not, and had those nine days crossed a month end, the accounts would have said so too.

The fix was to read the balance activity instead, and the lesson generalises. Parse the report whose running total is the provider’s balance, because that is the figure the clearing account is going to be compared with.

Compare daily, and write down every difference

The comparison runs every day rather than at month end, because a difference is cheapest to explain while it is small and recent. Each check stores both figures, what ours is made of, and the gap between them. A gap of zero needs nothing. Any other gap needs a note before the month can close, even when the note only says that a known line is on its way, because a difference nobody wrote down looks exactly like a difference nobody understood when somebody asks about it a quarter later.

What the balance is made of

Money owed by each payment provider at year end, grouped by reasonFour vertical bars showing what each payment provider owed the business at the year end. Card terminal, one thousand two hundred and seven pounds, all in transit, meaning sold before the year end and paid out after. Online checkout, one thousand six hundred and forty-two pounds, also in transit. PayPal, five hundred and sixty-eight pounds, unwithdrawn and left on the provider's balance. Marketplace, one thousand nine hundred and sixty-three pounds, held back as reserve to be released later. A note says this is five thousand three hundred and eighty pounds across four providers at 31 March, that a year earlier it was four thousand two hundred and eleven, and that neither figure appeared anywhere in the accounts.£0£1000£2000£3000£4000~£1207Card terminal~£1642Online checkout~£568PayPal~£1963MarketplaceIn transit: sold before year end, paid out afterUnwithdrawn: left on the provider's balanceReserve: held back, released later£5,380 across four providers at 31 March. A year earlier it was £4,211. Neither figure appeared anywhere in the accounts.
Fig 2. The same £5,380 grouped by why it was still with the provider. In transit clears within days, unwithdrawn waits for somebody to press a button, and reserve waits for a date.

An asset nobody was carrying

Every one of those pounds belongs to the business. In transit is sales made on the last days of the year and paid out in the first days of the next; unwithdrawn is a PayPal balance nobody had moved; reserve is the marketplace holding back part of its recent settlements. Booked from the bank, all £5,380 did not exist until it arrived, and then it arrived as sales of the following year.

That is a smaller distortion than netting fees off sales, and a more awkward one, because it moves income between years rather than between lines. In the worked year it came to £1,169, the growth in what the providers were holding. The clearing account removes it without anybody having to think about it: the balance at 31 March is the asset, and the sales stay in the year they happened.

The next post is the part of every report no parser can type: the adjustment lines with a sentence where a type code should be.

All posts