How to reconcile marketplace payouts with an API

1. Quantify the actual reconciliation backlog

Before building anything, get an honest number: across your merchant base, how many settlement statement pages does your platform process manually each month, and where does the time actually go? Most platforms underestimate this significantly, because the work is distributed across an ops team's individual tasks rather than tracked as one line item. A quick audit — pull a representative month's statements, count pages, and time how long a typical statement takes an analyst to reconcile by hand — turns a vague sense of "reconciliation takes a while" into a concrete monthly page count everything else in this guide is sized against.

This number matters beyond justifying the project internally — it's also what step 4's concurrency setting gets sized against, and what step 8's ongoing spend gets compared to once the pipeline is live. Platforms that skip this step tend to under-provision their batch worker later, discovering the real volume only once a large merchant cohort's statements are already flowing through it.

flowparse.io

2. Get an API key and pilot against real statements

A free plan account issues a real key against a smaller monthly allowance, processing documents at the same accuracy as a paid plan. The first useful test isn't a demo document — it's five or ten real settlement statements from processors your platform genuinely handles today, ideally ones already reconciled manually by an ops analyst so the extracted output can be compared line-by-line against a known-correct answer.

Resist the temptation to pilot only with your cleanest processor's statements — the pilot is far more useful if it includes at least one genuinely hard case: a smaller regional processor, a CSV export with unusual formatting, a merchant with a high chargeback rate producing a longer, denser statement. A pilot that only ever sees ideal documents produces false confidence that evaporates the first time a real edge case shows up in production.

const res = await fetch("https://api.flowparse.io/v1/extract", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form, // real settlement statement PDF or CSV
})
const result = await res.json()
// compare result.data against what an ops analyst entered manually
// for the same merchant, including every line item's category and reference

3. Build the merchant and processor tagging pipeline

Whatever already collects settlement statements today — a shared inbox, a processor's API pull, a merchant-facing upload portal — needs one addition: tagging each statement with a merchant and processor identifier before it's queued for extraction. This is the single piece of infrastructure every later step depends on, since the extraction API itself holds no concept of merchant or processor at all.

Platforms that already run some kind of structured merchant registry usually find this step is mostly plumbing rather than new design — the merchant and processor IDs already exist in your data model; the work is wiring the statement intake to attach them before extraction.

flowparse.io

4. Build the concurrent batch worker

A simple worker pool — 10 to 25 concurrent requests to start — turns a queue of tagged statements into extracted, validated results without processing them one at a time. This is described in full, with a code example, on the settlement line matchingfeature page; the short version is that concurrency is what makes a full merchant roster's settlement close finish in minutes rather than hours.

Start deliberately conservative on concurrency and increase it once the pipeline has run cleanly for a cycle or two — a low starting concurrency makes any bug in the tagging or result-handling logic easy to spot and fix on a small number of statements, rather than discovering it simultaneously across a large multi-processor batch on day one.

flowparse.io

5. Build the low-confidence review queue

Every extracted result carries a confidence and validation signal. Route anything below a threshold you set — start conservative — into a queue an ops analyst or finance reviewer works through, separate from the results confident enough to flow straight into matching. This single decision is what determines whether the extracted data feels trustworthy to your finance team or feels like a black box nobody can verify.

A simple, workable first version of this queue is often nothing more than a shared spreadsheet or a lightweight internal tool listing flagged statements with a link back to the source file — the sophistication of the review interface matters far less at first than making sure flagged statements are visible and get looked at before they reach a merchant-facing ledger.

flowparse.io

6. Wire typed line items into your matching logic

Extracted JSON maps onto the same fields your matching logic already expects — merchant, currency, period, gross sales, a typed line-item array and net payout — so this step is usually the fastest in the whole rollout. There is no separate data model to build for extracted statements; the goal is that your matching engine treats a validated extraction result exactly like any other structured input.

Where your platform already has a clean abstraction between "raw statement" and "matched line item," this step can be genuinely trivial — a new adapter that writes the same shape a manual entry already writes. Where that abstraction doesn't exist yet, building it here pays off well beyond this one integration, since it's the same seam any future data source would need anyway.

flowparse.io

7. Roll out to the first wave of merchants and processors

Pick your highest-volume processor first — commonly the one carrying the most merchants or the most statement pages, since that's where the time savings are most visible — and run the API pipeline in parallel with existing manual reconciliation for one full settlement cycle. Compare the two outputs. Once they consistently match, cut those merchants fully over and add the next wave. This gradual, comparison-driven rollout is what lets a platform trust the system before it feeds a merchant-facing ledger for the whole book.

Pick the comparison metric before starting, not after — most platforms compare net payout and line count per statement, since those two numbers catching any discrepancy is a strong enough signal without requiring a line-by-line manual diff of every field on every statement in the first wave.

flowparse.io

8. Monitor coverage and accuracy as merchant count grows

Once live, track two numbers on an ongoing basis: match rate (what share of statements processed each cycle flow straight through to matching without a review flag) and the rate of statements flagged low-confidence, which should stay low and roughly stable — a rising trend usually means a new processor or an unusual merchant category has entered the mix and is worth a quick look.

A brief monthly review of both numbers — five minutes, not a formal report — is usually enough. The goal isn't exhaustive monitoring; it's catching the two failure modes that actually matter: a backlog that quietly reopened because a new processor onboarded with statements nobody tagged for the pipeline, and a confidence-flag rate that stopped tracking normal for a reason worth understanding before it compounds.

flowparse.io

Who should own each step internally

A full worked rollout, start to finish

A 300-merchant platform audits its backlog (step 1) and finds roughly 1,200 settlement pages a month across four processors. An ops lead spends an afternoon running the highest-volume processor's most recent statements through a free API key (step 2), comparing the output against last cycle's manual entries — the fields match closely enough to proceed. Over the following two weeks, an engineer builds the tagging pipeline and a 15-concurrency batch worker (steps 3–4), and reconciliation ops sets an initial conservative confidence threshold for the review queue (step 5). Extracted JSON is mapped into the platform's existing matching logic as a new data-source adapter (step 6). The highest-volume processor's merchants run in parallel with manual reconciliation for one cycle (step 7); output matches, and they cut over. Over the following two months, the remaining processors follow in waves, with the review-queue threshold loosened gradually as trust in the extraction quality builds (step 8), until platform-wide reconciliation runs on the pipeline with only genuinely ambiguous statements reaching a human.

How long each step takes

Doing this with a small ops team versus a larger platform

A small marketplace with a handful of engineers follows the same eight steps, just compressed into fewer people's time rather than split across dedicated roles — the pilot, the pipeline (often a much simpler script rather than a full worker-pool system at first), the review, and the matching- logic wiring are handled by whoever is closest to the finance product, which if anything makes the review-queue step more valuable, since it's the thing protecting limited engineering time from being spent re-checking statements that were already extracted correctly. A larger platform with a dedicated reconciliation-ops function splits the work roughly along the roles table above, with the main advantage being that steps 3–4 and steps 5–8 can run in parallel rather than sequentially.

Common mistakes in this rollout

The most common mistake is skipping the review queue and treating every extraction as automatically correct from day one — even at strong accuracy, a small fraction of real-world statements are genuinely ambiguous, and a platform that doesn't catch those early risks a merchant questioning a payout figure that turns out to be wrong. The second most common mistake is cutting a processor over to the new pipeline without a parallel-run comparison first — skipping step 7's validation step to save time usually costs more time later, correcting an error a merchant noticed instead of one caught before it ever reached them. A third, subtler mistake is treating order matching as the extraction API's job rather than the platform's own logic's — building a workaround for a problem the API was never meant to solve.

flowparse.io

Best practices for a durable pipeline

Roll out gradually, processor by processor or wave by wave, rather than switching every merchant over on one date — this is the single highest-leverage practice in this guide, since it bounds the blast radius of any surprise to a small subset of merchants rather than every merchant's ledger at once. Keep the review-queue threshold visible and adjustable rather than hard-coded, so it can loosen as trust builds without a code change. And keep a simple weekly glance at the confidence-flag rate — it is the earliest signal that a new processor or an unusual merchant category has entered your mix before it becomes a bigger problem.

API reliability and what happens during an outage

Treat a failed extraction call the same way you'd treat any external API hiccup — retry with backoff, and if it still fails, queue the statement for a later retry rather than blocking the whole close. A brief service interruption affects only the statements in flight at that moment; nothing about a batch pipeline built with independent, retryable calls requires the whole system to be perfectly available at every instant to keep working.

Questions worth asking any extraction vendor, not just FlowParse

Whichever extraction API a platform ultimately chooses for this pipeline, a short list of questions separates a vendor built for genuinely varied processor coverage from one that will need to be replaced once the merchant base grows: Does the pipeline generalize across real-world statement formats, or is it tuned to a fixed list of supported processors? Is every line item typed and referenced, or only raw text extraction? Is balance and arithmetic validation included? Is there a genuine free tier to pilot against real settlement statements? A vendor that can't answer these plainly is worth a second look before committing production volume.

flowparse.io

A note on data residency and regulatory requirements

Marketplace and payments platforms handling merchant financial data are frequently subject to their own data-handling obligations, on top of whatever regulatory framework their merchants themselves operate under. Before sending production volume through any extraction vendor, confirm where processing actually happens, how long — if at all — original statements are retained, and whether that aligns with your platform's own merchant agreements and any regulatory framework it operates under. This is a conversation worth having explicitly during the pilot phase (step 2), not discovered after full rollout.

Documenting the pipeline for the next person who touches it

A reconciliation pipeline built by one engineer or ops lead over two weeks is easy to understand while it's fresh and hard to reconstruct a year later when it needs a change and the original builder has moved to a different team. A short internal document — which processors route through the pipeline and why, where the merchant-tagging identifiers come from, what the current confidence threshold is and who last changed it, and where the review queue actually lives — pays for itself the first time someone other than the original builder needs to debug a flagged statement or extend the pipeline to a new processor.

This doesn't need to be an elaborate specification. A single page covering the data flow (where statements come from, what gets tagged, where results land), the current operational thresholds, and a short list of known edge cases the team has already run into is enough to make the pipeline maintainable by whoever inherits it. Platforms that skip this step tend to rediscover the same edge cases repeatedly, once per engineer who touches the pipeline, rather than accumulating institutional knowledge about it.

It's also worth recording, in the same document, the reasoning behind the initial confidence threshold and any adjustments made to it over time — a future team member loosening the threshold without knowing why it was set conservatively in the first place is a common way trust in the pipeline erodes quietly, long after the people who built it have moved on.

A printable rollout checklist

Who this guide is for

Product and engineering leads at marketplace and payments platforms planning to automate a growing reconciliation backlog, and anyone evaluating whether their current merchant base's growth is outpacing what their manual reconciliation process can sustainably handle.

Scaling from a pilot to platform-wide coverage

The infrastructure built in steps 3–6 doesn't need to be rebuilt as merchant count grows — a worker pool handling twenty-five concurrent requests for 300 merchants handles the same load pattern for 1,500, just with a longer queue and, if needed, a higher concurrency setting. The rollout itself is what scales gradually (wave by wave); the underlying pipeline scales flat.

This flat scaling property is worth contrasting explicitly with the alternative: a platform relying only on manual reconciliation has to add headcount roughly in step with merchant growth. A platform with this pipeline in place solves the extraction question roughly once, then mostly just watches the numbers in step 8 as coverage grows underneath the same pipeline.

A short glossary

One habit worth keeping after rollout

Once the pipeline is fully live, the single habit worth keeping indefinitely is the weekly glance at the match-rate and confidence-flag numbers from step 8. It costs a few minutes and is the earliest warning that a new processor onboarded with statements nobody tagged, or that a processor has changed its statement layout — catching that in a weekly glance is far cheaper than discovering it in a merchant's question about a payout that doesn't look right.

Beyond that one habit, resist the urge to keep tinkering with the pipeline once it's stable — a batch worker, a tagging scheme and a review queue that are working don't need continuous engineering attention. The steps in this guide are meant to be built once and largely left alone, with the weekly monitoring glance as the only ongoing ritual worth keeping.

If you take one thing from this guide beyond the eight steps themselves, make it this: the hardest part of this rollout is not the engineering, and it was never really about the API. It's the sequencing and the trust-building — proving the pipeline works on a small, comparable sample before asking anyone, your team or a merchant, to rely on it for a whole reconciliation cycle. Get that sequencing right and the rest of this guide is mostly mechanical.

Frequently asked questions

Keep reading