Turned a marketplace's payment integration into one that fails safely, not silently

The Client runs a multi-seller marketplace — sellers list products, customers buy them, and the platform splits the money between itself and whichever seller fulfilled the order. It was already live, with real sellers and real customers, when they came to us.

They didn't need an outside team to audit their system and hand back a report, and they didn't need something built from scratch. They needed engineering capacity added directly to their own team — people who could pick up real tasks, go through the same review process as anyone else on the team, and be trusted with the parts of the system where a mistake means real money moving incorrectly.

That's the engagement we ran: embedded, not external.

What "embedded" actually meant, day to day

Being embedded isn't the same as being handed a spec and disappearing until it's done. Every phase of work was broken down into the same milestones and tasks the client's own team used, and everything we wrote went through the same review process anyone on the team would go through — nothing merged just because we were the ones who wrote it.

That mattered more than it might sound. On a system where a single bug can mean money silently going to the wrong place, a second set of eyes that treats a review like a real gate — not a formality — is the difference between catching a mistake before it reaches production and finding out about it from a customer. Several rounds of that review process caught real, serious problems before they ever shipped, which is most of what this case study is actually about.

We also didn't treat the relationship as one-way. When a request came in that looked like new work being folded into an existing phase for free, we said so directly, in writing, and proposed it be scoped and tracked properly — while still delivering everything that was actually part of the agreed work at no extra cost. Being embedded means acting like part of the team, not like a vendor who says yes to everything to keep the relationship smooth.

A marketplace with real money moving through it

Every order on the platform can involve multiple sellers, each getting their own cut once a payment clears. That means the system has to keep several things in sync at once: what the customer ordered, what each seller is owed, what's actually been paid, and how much stock is left — and it has to keep all of that consistent even when a payment fails, gets refunded, gets disputed, or arrives out of order.

The platform connects to a regional payment processor to handle checkout and payouts, and to an ERP system to keep accounting and invoicing in sync — both are widely used systems, not something unique to this platform, which is part of why getting the integration right mattered: it's a well-known category of problem, and well-known problems still get built wrong all the time.

The first audit surfaced real problems before we changed anything

Before writing anything new, the first phase of work was a straightforward audit of what already existed. It turned up several concrete problems:

A requirement in the existing specification contradicted itself — one part required a fix that could only be made a certain way, while another part explicitly forbade touching the exact piece of code that fix depended on. The specification, as written, was asking for something structurally impossible.

A shipping-rate integration had never actually left test mode. It was still pointed at the provider's sandbox environment, with a comment from the original build simply noting "switch to production later." Nobody had. It had looked like a working integration in every demo, because sandbox mode returns valid-looking responses — it just wasn't the real one.

An entire notification capability didn't exist. Sellers were supposed to be notified by email as they moved through onboarding and approval, but there was no email-sending capability anywhere in the system to do it.

A security control meant to gate an admin-only area looked correctly configured, but due to how the underlying framework evaluates permissions, it was never actually being applied — the area it was supposed to protect was effectively unguarded, and nothing in normal use would have revealed that.

Each of these got fixed with the smallest change that actually closed the gap, reviewed and explicitly signed off on rather than expanded into a bigger rewrite. That phase shipped 8 new endpoints and 77 new tests, and every one of the 156 pre-existing tests it ran alongside still passed.

Nothing about payments shipped on the first pass

The payment integration was the highest-stakes part of the whole engagement, and it was treated that way: the implementation went through three full rounds of review before anyone accepted it as correct. Each round caught a real, distinct class of problem — not style nitpicks.

One issue: the check that verifies an incoming payment notification hasn't been tampered with was reading a version of the request that had already been altered by an earlier processing step — meaning the verification could technically pass even against data that had been changed after the payment processor sent it.

Another: if a required security setting was ever missing, the system's default behavior was to accept the incoming request anyway rather than reject it — a fail-open default in exactly the place that should fail closed.

Another: there was a brief gap between the system checking "have I already handled this event?" and actually recording that it had. Payment processors routinely deliver the same event more than once as a normal safety measure — and in that gap, two near-simultaneous deliveries of the same event could both slip through and both get processed, instead of the second one being correctly recognized as a duplicate.

Another, the most consequential: the refund process could tell the payment processor to send money back to a customer before the marketplace's own records had confirmed that refund. If the processor succeeded but the internal record-keeping failed right after — a real failure mode, not a theoretical one — the money would already be gone with no matching internal record of it.

And underneath all of it: two separate parts of the system were each independently allowed to update the same financial record, using two different sets of rules for what counted as "paid" or "refunded." One of those paths was removed entirely, so a financial record can now only ever be changed one way, by one process, using one set of rules.

By the time this shipped, it was backed by 432 unit tests and 40 integration tests — a level of coverage that matches how much was riding on it being right.

A safety net for anything that still slips through

Even with all of that, we didn't treat "correct on the first try" as good enough for money. A scheduled process runs on its own every night, walks back through recent transactions, and compares the marketplace's own records against what the payment processor and the ERP system actually report. Anything left in an inconsistent or stuck state gets automatically corrected — the same refund problem described above, for instance, now has an automatic second pass that resolves it even if the very first attempt at fixing it failed.

The goal wasn't to make failures impossible. It was to make sure nothing stays broken quietly.

Growing the platform without losing the discipline

The engagement didn't stop at payments. In parallel, we helped build a new seller tier where the platform itself — not the seller — handles fulfillment and invoicing, letting sellers who don't want to manage logistics still sell through the marketplace. Roughly 70% of that work was designed to run alongside the payment integration rather than wait behind it, so the platform kept moving forward on more than one front at once.

We also took the customer-facing storefront from mostly untranslated — a small fraction of its pages actually supported the local language — to fully commercially ready: translated, mobile-responsive, and held to explicit performance and accessibility targets rather than "looks fine to us."

What Changed

The platform went from having two different, quietly conflicting ways to update the same financial record to having exactly one. Failures that used to be invisible — a stuck refund, a duplicate event, a security check that wasn't really checking anything — now surface and get corrected automatically instead of waiting to be discovered by a customer or a support ticket. The storefront went from a partially translated, unevenly tested interface to one built to an explicit commercial and accessibility bar. And the platform picked up a new way for sellers to participate without taking on fulfillment themselves, without slowing down the payment work already in flight.

Where It Stands Now

The relationship didn't end when the payment integration shipped. Our engineers are still embedded with the client's team today, five months in, continuing to work through new phases of the platform's growth the same way this one started: as part of the team, not alongside it.

The Stack

Backend
NestJS • TypeScript • PostgreSQL

Frontend
Next.js • React • TypeScript • Tailwind CSS

Integrations
Mercado Pago • Bling

Reliability
Idempotent Processing • Automated Reconciliation

Observability
Structured Logging • Error Tracking (Sentry)

Testing
Automated Unit & Integration Testing