Payments Platform Problems: The 7 That Cost Real Money, and How to Avoid Them

Why does the ledger keep getting scoped out of the first release?

Nearly every failed payments build we are asked to rescue started with the same plan: checkout first, then payouts, then dashboards, with the ledger somewhere in phase two. The reasoning is understandable. Checkout is visible to the board, the ledger is not, and Stripe already shows a balance that looks authoritative. So the team builds an order state machine, a payouts screen and a merchant portal on top of the processor balance, and it works until the second money source appears.

This matters more in payments than in most software. Elsewhere a wrong number is a bug you patch. Here a wrong number is a liability you owe a real person, and you cannot fix it by editing a field, because the value has already been paid out, reported to a seller and posted to your general ledger. A marketplace running Stripe for domestic cards, Adyen for European local methods and a bank file for the sellers who negotiated wire terms has three opinions about what settled and none of them can see the others. The orders table becomes the de facto ledger with a status column, and a status column cannot express a liability accrued in January that refunded in March.

The fix is unglamorous and it has to go first. A real double entry ledger with immutable append only journal entries, a hard database constraint that debits equal credits per transaction, and balances derived by summing entries rather than stored as a mutable number. Processors become sources of events, not sources of truth. When Stripe and your ledger disagree, your ledger wins and the difference opens a reconciliation exception with a ticket attached rather than becoming folklore.

What goes wrong when three years of transactions move into a new ledger?

Historical migration is the most underestimated line in a payments project and it is routinely 3 to 5 weeks on its own. The problem is not volume. It is that the history was produced under rules you no longer run. A seller was on a 12 percent take rate until August, then 9 percent, and the change was applied by editing a config value with no effective date, so nothing in the data records when it happened. A refund in 2023 was processed by issuing a credit outside the platform because the button did not exist yet. Two hundred orders were adjusted manually by a controller who left.

Load that into a clean double entry model and the closing balances will not tie out, which is exactly the signal you wanted, and exactly the thing that stalls a launch. Teams then do the wrong thing: they plug the difference into a suspense account and go live, which converts an unknown into an accepted permanent error.

What works is opening balance discipline. Do not attempt to reconstruct every historical journal entry. Pick a cutover date, migrate only the balances that must be correct on that date, seller by seller, and prove each one against what the processor already paid. Everything before the cutover stays retrievable in the old system as a read only archive. Then run the new ledger in shadow mode alongside the existing process for at least two full payout cycles and compare every line, not the totals. Totals agreeing while lines disagree is the classic false pass, and it will surface three months later as a seller dispute.

Why do processor and bank feeds break after launch?

Integrations in this category do not fail at the API. They fail at the file. Stripe balance transactions arrive by API and behave predictably. Adyen settlement detail reports arrive by SFTP on a batch schedule and change shape when a report version is upgraded. The bank sends BAI2 or MT940 with a memo field that a human at the bank populates inconsistently. NACHA returns arrive days later with codes your code has never seen.

The specific post launch break is a silent one. The webhook that used to arrive twice a second now arrives once, or twice, or not at all, and nothing alerts because the request that never came cannot log an error. A processor changes a report column order and your parser reads the fee column as the net amount for four days before anyone notices, by which point the ledger has 40,000 wrong entries.

Three defences, and they cost very little if built at the start. First, idempotency: write an inbound event log before you process anything, keyed on the processor event identifier, so a duplicate is a no-op and a replay is safe. Second, never trust delivery. Run a polling reconciliation job that pulls the authoritative list from each processor on a schedule and compares it against what you received, so missed events are detected rather than assumed away. Third, validate file structure on ingest and fail loudly. A parser that rejects an unexpected column layout and pages someone is worth far more than one that quietly continues.

What happens when PCI scope and money transmission posture are not covered?

These two get skipped because they feel like legal questions rather than engineering ones, and they are the two that can invalidate a finished build.

Payment Card Industry Data Security Standard scope is decided by where a card number goes. If a card number never touches your servers, because tokenisation happens in the browser or app using your processor's hosted fields, you stay at the simplest self assessment level. If a raw card number appears anywhere in your infrastructure, including a debug log line written during a bad week, you fall into the heaviest self assessment tier with network segmentation, quarterly scanning and audit cost attached. We have seen a launch delayed by two months because a well meaning developer logged the full request body of a checkout endpoint. Nothing was breached, but the log store was in scope, and proving it clean took longer than building the feature.

Money transmission posture is the bigger one. Riding a processor's licences, where funds sit with the processor and you instruct movement, is a different regulatory world from taking custody of funds yourself. That single decision changes your legal review, your controls, your audit obligations and your calendar substantially. It is the largest cost driver in this category, and it belongs in the first conversation, not the third. Any developer who does not ask which side of that line you are on has not shipped a payments platform.

Should you build custom or configure what you already own?

Genuinely, most operators reading this should not build. If payments are a cost centre rather than part of your margin, meaning you charge a card, keep the money and owe nothing to a third party, Stripe plus a competent bookkeeper is correct and a custom platform is a vanity project. If you are a marketplace under roughly $2 million in annual volume with straight percentage splits, Stripe Connect handles that natively and handles it well. Configure Connect properly, spend the money on demand generation, and revisit this in two years.

If your only real pain is matching bank credits to processor payouts, buy Modern Treasury or Ledge. They are good products solving a narrow problem, and rebuilding them to save a subscription is bad arithmetic. Configure them, connect your accounts, and accept that they will not model your bespoke rules.

The signal that configuration has run out is when your reconciliation exceptions are business logic rather than data matching. If the reason a payout was short is a prior period chargeback your terms say gets netted from the next cycle, no vendor will encode that, because the rule lives in your grower or seller agreement and in your head. Two or more processors live in production, a close longer than three days, and payout disputes settled by refunding rather than explaining are the other three signals. When three of the four are true, build the ledger. You can keep buying the acquiring.

How do hidden costs get into the quote?

Payments quotes go wrong in predictable places, and all of them are visible before signature if you ask.

• Fee rules. Every operator says they have a few bespoke fee rules. Every operator has about thirty. Tiered seller shares, referral partner splits with an expiry, negative fees on subsidised orders, jurisdiction withholding, reserves on new sellers. Count them before the quote, in writing.
• Currencies. Multi-currency is not a formatting task. It is rate sourcing, spread accounting and a rounding policy that touches every ledger entry. Adding a second currency late is a rework of the core model.
• Payout rails. Each rail is its own file format, its own return codes and its own reconciliation shape. Three rails is roughly three integrations, not one with options.
• Historical migration. Assume 3 to 5 weeks and get it named as a line item with its own acceptance criteria, which should be balances tying out seller by seller.
• Dispute and chargeback workflow. Evidence assembly is a real module. It is frequently assumed to be included and almost never is.

The pattern to insist on is a phased contract where you can stop after phase one and keep everything built, source code included, in your own repositories and cloud accounts.

What separates a payments build that works from one that fails?

Four things, and you can test all of them in a single conversation before you sign anything.

Ask the team to whiteboard the double entry model for a marketplace order with a partial refund and a chargeback in a later period. This takes ten minutes and it is the whole interview. A team that has done this reaches for accounts and journal entries immediately and asks about your account tree. A team that has not reaches for a status column on an orders table. There is no faking it.

Ask which settlement report formats they have parsed in production, by name. You want specifics: Adyen settlement detail, the difference between Stripe's API and its reports API, BAI2 from the bank, NACHA return codes. Anyone who has shipped reconciliation has a war story about a file format. Generalists talk about webhooks, which is the easy tenth of the problem.

Ask what happens when the same webhook arrives twice, and when it never arrives at all. Idempotency keys, an inbound event log written before processing, and a polling job that catches missed events. Teams that have been burned answer instantly.

Finally, insist that every payout run is dry runnable and stores its full calculation trace, every input line and every rule version applied, attached to the payout record. That single requirement is what turns a seller dispute from a $180 goodwill credit into a one click explanation, and it is the difference between defending your own maths and paying to avoid the conversation.