When a product manager asks how long it will take to integrate a new payment processor, the answer they want is a number of weeks. The answer they get from an engineer who has done it before is usually a long pause, followed by a question: "Do you mean to a working demo, to production, or to the point where I can stop thinking about it?"
Those are three very different timelines, and the gap between them is where the real cost of payment integration lives. The first integration any team does feels manageable. The processor's documentation describes the API, sandbox credentials are easy to obtain, and a basic happy-path transaction works within a few days. Everyone is optimistic. The optimism does not survive the second month.
The visible cost
The visible cost of a payment integration is the work everybody can see and estimate. It's the API client, the request signing logic, the response parsing, the error mapping, the database schema for storing transaction records, and the unit tests. For a competent engineer working with a reasonably documented processor, this work is real but bounded. Two to four weeks is a fair estimate for a clean integration that handles authorization, capture, refund, and void operations against a single processor's sandbox.
This is the number that ends up on the project plan. It is also the number that consistently misleads everyone involved.
What sandbox doesn't tell you
Sandboxes are designed to demonstrate that the API works. They are not designed to demonstrate how the system actually behaves in production, and that gap is where most of the underestimation lives.
In the sandbox, declines come back instantly. In production, they sometimes come back after a 45-second timeout. In the sandbox, every authorization is followed by a clean settlement record the next day. In production, settlement files arrive late, contain transactions you don't recognize, and occasionally omit transactions that you definitely processed. In the sandbox, refunds work the same way every time. In production, the same refund call against the same transaction will succeed today and fail tomorrow because the transaction has crossed a settlement boundary that doesn't exist in the sandbox at all.
The first time you discover this in production, the cost is not the engineering hours required to fix it. The cost is the merchant who called support because their daily totals don't match, the support engineer who escalated to operations, the operations engineer who escalated to engineering, the engineer who had to reconstruct what happened from incomplete logs, and the trust the merchant lost in the meantime. None of that appeared in the original integration estimate.
Certification is not optional and not cheap
Almost every payment processor of any size requires a certification process before you can use them in production. The processes vary in formality, but they share the property of being slower and more bureaucratic than the engineering work they certify.
Certification typically involves running a fixed set of test cases against the processor's certification environment, recording the results, and submitting them for review. The test cases include scenarios you would never encounter in normal development: specific card numbers that produce specific decline codes, transactions that must be voided in a particular sequence, edge cases involving partial captures and tip adjustments. Each test case has expected behavior, and your integration must produce that exact behavior — not approximately, not equivalently, exactly.
The first certification cycle is the longest. You will discover that your integration handles things in a way that the processor considers wrong even though it works. You will rewrite logic that you were sure was correct. You will wait days for review feedback. You will resubmit. You will be told that one test case failed because of a field you did not know existed. You will fix it. You will resubmit. Eventually, you will pass.
The total elapsed time for first certification with a major processor is rarely less than six weeks and is often three months. The engineering hours involved are smaller than the calendar time, but the calendar time is what determines when you can launch.
The edge cases you have to discover yourself
Every payment processor has undocumented behaviors. Some of them are documented but in places nobody reads. Some are documented in old PDFs that contradict the current API reference. Some are not documented anywhere and exist only in the institutional memory of the processor's support team.
A short list of things I have personally discovered the hard way, all of which were absent from the official documentation:
- One processor returns success for a void request that arrives after the transaction has already settled, but the void doesn't actually do anything. The merchant's account is unchanged. The only way to know is to pull the settlement file the next day.
- Another processor has a soft maximum on authorization amounts that depends on the merchant's risk profile. Exceeding it doesn't return an error — the authorization succeeds but is silently flagged for manual review, and the funds are held without notification.
- A third processor accepts ISO 4217 currency codes in the API but rejects certain valid codes for certain merchant accounts based on their underwriting region. The error message is generic.
- A fourth processor changes the format of its transaction reference numbers between the authorization response and the settlement file. The two values are related but not identical, and the relationship is not documented.
Each of these took a real production incident to discover, followed by hours of debugging, followed by a permanent piece of code that handles the case. Multiply this by the number of processors you support and the number of years you operate, and you start to understand why payment integrations get more complex over time rather than less.
Reconciliation is the hidden second integration
Most teams plan a payment integration as one piece of work: connect to the processor's transaction API, send authorizations, get responses. They do not plan a second integration that is just as large: ingesting and processing the processor's settlement data.
Settlement files are how the processor tells you what actually happened with the money. They arrive on a schedule that varies by processor, in formats that vary by processor, with field definitions that vary by processor and sometimes by merchant within a processor. Some are CSV. Some are fixed-width. Some are XML. Some are delivered via SFTP. Some require an authenticated API poll. Some are pushed to a webhook. Some require all three depending on file type.
The work to ingest, parse, validate, and reconcile this data is not part of the integration estimate, but it is structurally part of the integration. Without it, you cannot answer the most basic operational question a merchant will ever ask: "Did I get my money?" And the work has to be done per processor, because no two settlement formats are alike.
Maintenance never ends
A payment integration is not a project that finishes. Processors change their APIs. They deprecate fields. They add required fields. They modify error codes. They migrate from one infrastructure to another and break clients that depended on undocumented timing behavior. They roll out new fraud rules that reject transactions you used to accept. They send emails about changes you have to make, and the emails go to the address that was in the original signup form, which is no longer monitored.
The ongoing maintenance burden of a payment integration, in my experience, runs to roughly 10–20% of an engineer's time per processor per year, and that's just for the integration to keep working — not to add new features. If you support five processors, you have a full-time engineer doing nothing but maintaining the integrations you already have. This is not a number that appears in any business plan I have ever seen.
Maintenance is also not evenly distributed. Most of the time, nothing happens. Then a processor sends a notification that they're sunsetting an endpoint in 90 days, and an engineer has to drop other work, understand the new endpoint, modify the integration, run the new certification process, and deploy without breaking production. Three months of planning gets disrupted by a one-paragraph email from a processor's account manager.
The support burden
Once a payment integration is in production, it generates support load. Most of it is not the integration's fault, but the integration is where the support load lands.
A merchant's customer disputes a charge. The merchant calls support. Support needs to retrieve the original transaction, the settlement record, the dispute notification, and any subsequent activity. This requires a tool, which requires a database query, which requires a schema that supports the lookup pattern, which requires an engineer to have anticipated it. If any link in that chain is missing, the support engineer has to ask engineering, and an engineer's morning is gone.
The time engineering spends on payment-related support tickets is the most underestimated cost of all, because it doesn't appear on any project plan and accumulates silently. I've seen organizations where one engineer was effectively doing payment support full-time without anybody acknowledging that the role existed. They were just "the person who knows how the integration works," and every payment ticket eventually found its way to them.
Why estimates are wrong
The fundamental reason payment integration estimates are wrong is that they conflate the API integration with the payment integration. The API integration is a software engineering task with a definable scope. The payment integration is an operational commitment with no definable scope, because it includes reconciliation, certification, edge-case discovery, ongoing maintenance, support tooling, and the institutional knowledge required to keep all of it working.
An honest estimate for adding a new processor to a POS platform that already has one or two looks more like this:
- Initial integration to working sandbox demo: 2–4 weeks of engineering time
- Edge-case discovery and production hardening: 4–8 weeks of engineering time, spread over 2–3 months of calendar time
- Certification process: 6–12 weeks of calendar time, with intermittent engineering effort
- Reconciliation and settlement pipeline: 4–6 weeks of engineering time
- Support tooling and runbooks: 1–2 weeks of engineering time
- Ongoing maintenance: 10–20% of an engineer's time, indefinitely
Adding these up, the first-year cost of a single new processor integration is somewhere between three and six months of engineering effort, plus calendar delays imposed by certification, plus a permanent ongoing cost. The original "two to four weeks" estimate was not wrong — it was just answering a different question.
What this means for architecture
The structural cost of payment integration is the most important architectural input nobody factors into their decisions. Teams routinely choose to add a new processor without understanding what they are committing to, then express surprise when the integration absorbs more engineering capacity than the rest of the platform combined.
The implication for architecture is that anything you can do to reduce the marginal cost of adding a new processor is worth a large upfront investment. A proper abstraction layer, a unified reconciliation pipeline, a generalized error taxonomy, a shared certification harness — these are not premature optimizations. They are how you keep the cost of integration #5 from being five times the cost of integration #1.
The teams that understand this build platforms. The teams that don't end up maintaining a portfolio of bespoke integrations that nobody can reason about anymore.
The honest conversation
The honest conversation to have with a stakeholder asking for a new payment integration is not "yes, this will take six weeks." It is: "We can have a sandbox demo in six weeks. We can have it in production in three months. We will be debugging edge cases for another three months after that. And from then on, it will absorb a meaningful fraction of one engineer's time, every year, for as long as we use it. Are you sure you want this processor and not one we already support?"
That conversation rarely happens, because the cost is invisible until it isn't, and by then the decision is made. But the cost is real, and it compounds, and if you don't account for it explicitly, it will show up as something else — slower feature velocity, more incidents, more burnout — and you will not be able to trace it back to its source.
The real cost of payment integration is not what it takes to write the code. It's what it takes to live with the code afterwards. Anybody who gives you a single-number estimate without distinguishing the two is selling you optimism, not engineering.
This is part of a series on payment systems architecture. See also why POS payment infrastructure is still broken and the hidden cost of processor fragmentation.