A settlement file is just an unposted Journal Entry

Every payment gateway eventually hands you a settlement file: here is what we collected on your behalf, here is what we kept as charges, here is what hit which bank account. In most finance teams that file meets a spreadsheet and an afternoon. Ours meets a parser, because a settlement file is — if you squint — just a Journal Entry that nobody has posted yet.

Reading the file like an accountant

Each settlement line answers three questions: which transactions were settled, into which account, minus what deductions. Mapped to double-entry, that is a debit to the bank account that received the payout, a debit to a gateway-charges expense account for the service fee and its tax, and a credit clearing the gateway receivable. So the pipeline does exactly what a careful accountant would:

• Match each payout line to a company bank account by account number — never by guesswork or ordering.
• Book per-transaction gateway charges (service charge plus tax) to a dedicated charges account, so the cost of collection is visible in the P&L instead of vanishing into netted-off totals.
• Post the result as a Journal Entry against the original Payment Entries — idempotently, so re-running a file never double-posts.

Split payments make this genuinely fiddly. One parent payment can fan out across sub-merchant accounts — different companies in the same ERPNext instance, each with its own chart of accounts. The mapping from gateway sub-merchant to company bank account is configuration, not code, and the poster resolves it per company. Multi-entity accounting is exactly the kind of thing you want the machine to be pedantic about.

Trust, but verify — on a schedule

Files arrive late, transactions miss files, and webhooks occasionally die in transit. So reconciliation is not an event, it is a schedule: sweeps re-query the gateway’s transaction API and re-process anything the ledger has not seen, through the same idempotent path. One gateway’s documentation recommends checking transactions about an hour after completion; we took them at their word and built the cron accordingly.

The payoff is boring in the best way. Collections land, charges are booked, payouts match bank statements, and the finance team’s reconciliation work shrinks to reviewing exceptions the system has already flagged — with the exact delta attached. Automation in accounting is not about removing humans; it is about only spending their attention where the numbers disagree.