Home/Research library/Operations That Don’t Scale

Guide · Integration and engineering

How Long Should a Payment Integration Take?

Consider a hypothetical integration. A developer gets the first sandbox payment working before lunch. Six weeks later, the payment method still has not launched. Where did the time go? Not necessarily into six weeks of coding. Some of it may have gone into merchant or provider on

Source-imported researchEditorial verification pending

Research draft awaiting independent review. This material was adapted from an existing research library. Provider-specific promotions have been excluded automatically; facts, regulatory requirements, and conclusions must be verified before the page is indexed publicly.

How Long Should a Payment Integration Take? From First API Call to Production Readiness

Consider a hypothetical integration.

A developer gets the first sandbox payment working before lunch.

Six weeks later, the payment method still has not launched.

Where did the time go?

Not necessarily into six weeks of coding.

Some of it may have gone into merchant or provider onboarding. Some into production credentials. Some into authentication. Some into webhook processing and payment-state handling. Finance may still need transaction identifiers and reports that make settlement reconcilable. Operations may need alerts and a recovery procedure. Production testing may expose differences that the sandbox could not reproduce.

The first API request proved something useful:

The merchant can communicate with the payment provider.

It did not prove:

The merchant can safely operate customer payments in production.

That distinction is the most useful answer to how long a payment integration should take.

There is no responsible universal number of days.

The useful timeline ends when the integration reaches controlled production readiness, not when the first test request returns success. The editorial brief makes that distinction the defining thesis of this pillar.

“How long?” is the wrong first question

Before estimating duration, define the finish line.

A payment integration can be called “complete” at several very different points.

Milestone 1: API connectivity

The merchant can authenticate and submit a valid request.

Milestone 2: First successful sandbox payment

The test environment produces the expected happy-path result.

Milestone 3: Functional checkout

A customer can move through the intended UI, authentication, redirect, or payment-method flow.

Milestone 4: Lifecycle-complete integration

The merchant can correctly process the important states and secondary operations:

success → pending → failure → timeout → asynchronous update → capture → cancellation → refund

as applicable.

Milestone 5: Production-enabled integration

Live credentials, accounts, endpoints, methods, currencies, webhooks, security configuration, and provider approvals are ready.

Milestone 6: Production-ready integration

Monitoring, incident ownership, customer-support handling, reconciliation, rollback and live validation are in place.

Milestone 7: Reconciled production readiness

Finance can connect merchant orders and payment records to provider transactions and actual settlement/reporting.

The difference between Milestone 2 and Milestone 7 is why “our API integration took one day” and “our payment project took six weeks” can both describe the same implementation without contradicting each other.

Engineering effort and calendar lead time are different metrics

This distinction should appear in every integration estimate.

Engineering effort

The amount of developer effort attributable to implementing and validating the integration.

Measure it in a consistent unit such as engineering hours or person-days.

Calendar lead time

Elapsed time between the approved project start and the defined production-readiness milestone.

Calendar time can contain work that developers do not control:

commercial setup;

merchant onboarding;

required reviews;

provider-account configuration;

acquiring setup;

payment-method enablement;

credentials;

QA coordination;

security review;

production testing;

Finance validation.

The brief explicitly requires these metrics to remain separate.

A payment team that estimates only engineering effort can therefore produce an accurate engineering estimate and an inaccurate launch date.

Think in critical paths, not task totals

A payment integration is a dependency graph.

Some work can happen in parallel.

Other work cannot begin until another step completes.

For example:

Commercial approval

Merchant/provider onboarding

Production account configuration

Live credentials

Controlled production test

Production validation

At the same time, engineering may run another chain:

Architecture

Core integration

Payment state

Webhooks

Failure handling

Test coverage

Monitoring

Finance may have a third:

Identifier model

Transaction reporting

Settlement data

Reconciliation validation

The go-live date is constrained by the longest dependent chain that must be complete—not by the duration of the API coding task.

Conceptually:

Production lead time = completion time of the integration’s critical dependency path.

That is why adding more developers does not automatically remove a merchant-review, acquiring, credential, payment-method, or reconciliation dependency.

The Payment Integration Critical Path

A robust estimate can be built across sixteen stages.

Scope

Before implementation, define:

product or integration type;

merchant entities;

countries;

currencies;

payment methods;

one-time vs recurring;

authorization/capture model where relevant;

refund requirements;

required customer authentication;

reporting/reconciliation needs;

production success criteria.

The scope should answer:

What exactly must this integration be able to do before launch?

A card-only one-time payment and an international recurring payment integration should not inherit the same estimate simply because both use an HTTP API.

Merchant and provider onboarding

Technical work can proceed while onboarding is incomplete, but real processing may still depend on:

provider account status;

commercial agreements;

required merchant information;

production account setup;

method enablement;

acquiring configuration;

applicable business/review requirements.

That is a useful general planning lesson even though other providers have different onboarding processes:

Technical integration and production enablement are separate dependencies.

Architecture

Decide which merchant objects and systems participate.

At minimum, avoid treating these as interchangeable:

Order

Commercial object describing what was purchased.

Payment intent

Merchant objective such as “collect €50 for Order 123.”

Payment attempt

One attempt to satisfy that objective.

Provider transaction

Provider-native object representing the payment operation on its system.

Those identifiers should not be collapsed casually, particularly if the merchant expects to add providers or migrate later.

Architecture work done here can prevent much more expensive rework after launch.

Core API integration

Now the team implements the provider interaction:

authentication;

request construction;

trusted amount/currency handling;

payment creation;

provider response parsing;

correlation identifiers.

A successful request confirms that part of the architecture.

It should not be mistaken for completion of the payment lifecycle.

An HTTP response and a financial payment outcome are different layers. The brief explicitly distinguishes API failure from payment failure: an API request can time out while a financial operation succeeds, while a technically successful API exchange can return a genuine payment decline.

Checkout and client work

Depending on the architecture, this may include:

hosted checkout;

provider UI components;

client-side tokenization;

wallet flows;

authentication;

redirect handling;

mobile/app-switch handling;

customer-return routes.

Sensitive decisions such as authoritative price and currency should remain within an appropriately trusted merchant boundary rather than being blindly accepted from tamperable client input.

The exact boundary depends on the provider’s documented architecture.

Payment-state design

A production integration usually needs more than:

success

and:

failure.

Depending on the method, useful concepts may include:

created;

requires customer action;

submitted;

pending;

authorized;

completed/captured;

failed;

canceled;

expired;

reversed;

refunded;

unknown.

No universal state machine fits every provider or method.

The important point is that state semantics must be explicit.

This work often separates a demo integration from an operable one.

Unknown is a real state

Suppose the merchant submits a payment request.

The connection closes before a response arrives.

What is the payment state?

Not necessarily:

FAILED.

The merchant knows only that it did not receive a definitive response.

The financial operation might:

never have reached the provider;

have been rejected;

still be processing;

already have succeeded.

The correct merchant representation may therefore be:

UNKNOWN

until the outcome can be established.

The brief requires unknown/unconfirmed state to be treated as a first-class concept and explicitly warns against retrying an unknown financial operation as if it were a known failure.

The detailed decision tree belongs in Handling Payment API Timeouts.

For project estimation, the important point is simpler:

If the integration cannot represent uncertainty, the project is not production-ready merely because the happy path works.

Webhook and asynchronous-event handling

Many payment systems continue to communicate after the initial request.

A production integration may need to handle:

asynchronous confirmation;

refunds;

reversals;

risk outcomes;

recurring events;

payment-method status changes.

Webhook implementation includes more than opening an HTTP endpoint.

The merchant may need:

receive → authenticate/verify → deduplicate → persist → process → validate transition → update payment state → acknowledge → monitor

The brief explicitly distinguishes event generation, delivery, receipt, validation, processing, and the resulting state update.

Its current technical review checklist also requires Pingback processing, rejection of invalid signatures, and duplicate-reference handling intended to avoid duplicate fulfillment.

Those are concrete examples of why “the checkout page opened successfully” is not equivalent to “the integration is ready.”

Error handling and idempotency

The integration should know the difference between:

request validation error;

credential/access error;

provider technical error;

network/transport failure;

timeout;

issuer/bank decline;

required customer action;

unknown result.

A generic implementation such as:

catch error

→ show "payment failed"

→ retry

is not a safe payment model.

Before retrying a financial operation, the system needs to understand:

What failed?

Is the payment state known?

Is this logically the same operation?

What idempotency behavior applies?

Could the previous attempt still be processing?

Could a new request produce a duplicate financial outcome?

The detailed mechanics belong in Payment Idempotency Explained and Handling Payment API Timeouts.

But estimating the project without allocating work for these failure paths underestimates the integration.

Authentication and payment-method-specific flows

One-time card authorization can be materially different from:

card + customer authentication;

recurring payment;

bank redirect;

delayed bank payment;

QR flow;

wallet;

mandate-based payment.

An asynchronous method can move through states such as:

customer initiated

→ redirected

→ instruction created

→ pending

→ customer returned

→ financial confirmation

A customer returning to the merchant site does not necessarily establish payment completion.

Every genuinely different lifecycle expands the integration’s state, test, support, and reconciliation surface.

Refunds and secondary operations

A payment project should specify which post-payment operations must be ready at launch.

Potential examples:

capture;

cancellation or reversal;

refund;

partial refund;

recurring cancellation;

transaction lookup.

A merchant that can collect customer money but cannot operate its normal refund process may be technically connected yet operationally incomplete.

Sandbox testing

The sandbox should prove specific things.

Useful tests can include, where the provider environment actually supports them:

happy path;

decline;

invalid request;

authentication;

pending state;

duplicate submission;

idempotent repeat;

duplicate webhook;

delayed webhook;

out-of-order webhook;

refund;

cancellation;

timeout simulation;

rate-limit handling.

The point is not to accumulate test cases.

It is to demonstrate that the merchant's payment model behaves safely under expected states and failures.

Sandbox success is not production readiness

A sandbox can test API contracts and deterministic merchant logic.

It generally cannot prove every property of the real payment ecosystem.

Production can introduce differences involving:

actual issuer behavior;

real customer behavior;

live authentication;

latency;

concurrency;

method availability;

provider limits;

settlement;

real fraud/risk decisions;

regional infrastructure.

The supplied brief explicitly requires sandbox validation and production validation to remain separate milestones.

So:

“All sandbox tests pass” should mean “ready for controlled production validation,” not automatically “production behavior is proven.”

Production configuration

Going live can require a new set of configuration checks:

live credentials;

correct merchant account/entity;

correct production endpoint;

enabled currencies;

enabled methods;

authentication configuration;

production webhook endpoint;

signing secrets or certificates;

production access controls;

live reporting configuration.

Provider-specific requirements need to be verified rather than inferred.

That is a good example of why environment assumptions must be verified per product rather than generalized.

Controlled live validation

The first real-money payment is another milestone—not the finish line.

A safer launch sequence can use a defined, controlled exposure where practical:

internal/live validation

→ limited eligible cohort

→ observe

→ expand

Guardrails might include:

technical-error rate;

unknown-state rate;

payment completion;

duplicate financial outcomes;

webhook-processing failures;

reconciliation exceptions.

There is no universal traffic percentage for a canary.

The correct exposure depends on transaction volume, risk, payment method, provider, and merchant tolerance.

Reconciliation and reporting

A payment integration needs sufficient identifiers to connect:

merchant order

→ payment intent

→ payment attempt

→ provider transaction

→ authorization/capture/completion

→ refund/dispute

→ settlement record

The detailed finance process may live elsewhere, but the integration has to create the data required for it.

This is another common gap between:

“The payment succeeded.”

and:

“Finance can prove where the money went.”

That capability can support a merchant reporting/reconciliation architecture, but the merchant still needs its own identifiers and matching logic appropriate to its business.

Monitoring and runbooks

Production readiness includes being able to answer:

What happened to this payment?

Useful observability can include:

merchant payment ID;

attempt ID;

provider transaction ID;

API operation;

latency;

response class;

provider-native state;

canonical merchant state;

retry count;

webhook status;

integration version.

Sensitive credentials and payment data should not be indiscriminately logged.

Operational runbooks should cover the failures the team is actually expected to handle.

Examples:

webhook processing stops;

unknown states accumulate;

production credentials fail;

provider API becomes degraded;

refund processing fails;

reporting/reconciliation stops matching.

A launch without an owner for those conditions is not a completed integration.

Launch

“Launch” should mean a defined readiness gate has passed.

Not:

someone changed a feature flag.

A useful production-readiness definition might require:

Payment correctness

Core customer flows and required secondary operations work.

State correctness

Pending, failure, completion, and unknown states are represented appropriately.

Asynchronous correctness

Relevant provider events can be received, verified, processed, and reconciled.

Retry safety

Repeated financial operations cannot blindly create duplicate outcomes.

Production configuration

Live accounts, credentials, methods, currencies, callbacks and environments are confirmed.

Security

Payment-data and credential architecture has received appropriate security review.

Finance

Payment identifiers and reports support reconciliation.

Operations

Monitoring, alerting, escalation and runbooks exist.

Customer support

Support can identify payments and respond to expected exception states.

Ownership

Someone owns the integration after launch.

When those gates are satisfied, “production ready” becomes an auditable state rather than a feeling.

Five integrations with five different critical paths

The same provider can produce very different project timelines depending on what the merchant is actually integrating.

Example 1: Simple one-time card integration

A comparatively narrow integration may require:

card payment collection;

authorization/payment creation;

one success path;

expected declines;

basic refund;

webhook/event handling;

production configuration;

reconciliation.

Its critical path may be dominated by core implementation plus production enablement.

Do not convert that into a universal number of days.

Example 2: Card + authentication + recurring payments

Now add:

customer authentication;

stored credential/token model;

initial versus subsequent transaction distinctions;

recurring states;

failed recurring attempts;

cancellation;

credential lifecycle;

additional support behavior.

The project is no longer simply the original card integration plus one API call.

New lifecycle and operational dependencies have been introduced.

Example 3: Local asynchronous payment method

The method may involve:

redirect or app switch;

pending state;

customer return;

later provider confirmation;

expiry;

late payment possibility;

method-specific refund behavior.

Its integration timeline may be dominated by state design and end-to-end testing rather than the initial payment-creation call.

The article Asynchronous Payment Methods should own those implementation mechanics.

Example 4: Multi-PSP integration

Adding another PSP can require:

another provider adapter;

merchant-controlled payment/attempt identity;

provider-state normalization;

routing or eligibility logic;

cross-provider observability;

additional reconciliation;

duplicate-attempt controls;

incident ownership.

The integration is now part of a multi-provider operating architecture.

That broader strategy belongs to the Multi-PSP and Payment Orchestration clusters, while this article's concern is the integration work required to make the provider maintainable.

Example 5: Provider migration

A provider migration has two timelines.

New transaction migration

When can new payments safely move to the new PSP?

Legacy transaction lifecycle

How long must the old provider remain accessible for:

refunds;

disputes;

pending payments;

recurring relationships;

settlement;

reporting;

transaction investigation?

The brief explicitly warns that migration is not simply:

integrate new PSP → disable old PSP.

A migration can therefore reach 100% new-payment routing while still being operationally incomplete.

The timeline should expose external dependencies

An estimate should not present every task as “engineering.”

For each critical-path item, identify:

Dependency

Typical accountable function

Merchant/provider onboarding

Payments/commercial/provider

Payment architecture

Payments engineering

Core API

Engineering

Checkout/client

Product/engineering

Payment state

Payments engineering

Webhooks

Engineering/platform

Security review

Security

Authentication

Engineering/payments/provider

Engineering/QA

Production credentials

Provider/payments

Live validation

Payments/engineering/operations

Reporting

Data/payments engineering

Reconciliation

Finance/payments

Monitoring

Engineering/SRE

Runbooks

Operations/SRE/payments

Launch decision

Cross-functional owner

The exact organizational model can differ.

What matters is making the dependencies visible.

A useful integration estimate has confidence levels

Early in the project, not every external dependency is known.

Instead of one false-precision deadline, estimate against confidence.

For example:

Known

API selected;

architecture approved;

integration scope;

engineering capacity.

Known dependency, uncertain duration

provider review;

production credentials;

acquiring enablement;

method approval;

security review.

Unresolved scope

token migration;

authentication path;

recurring behavior;

reporting format;

production-only requirement.

The schedule should become more precise as uncertainty is resolved.

A fixed launch date that silently treats every unresolved dependency as zero days is not a better estimate.

Optimize for time to production readiness, not time to demo

A very fast first payment can still be useful.

Track it.

The brief recommends separating at least these milestones:

Time to first successful sandbox payment

Useful developer-feedback metric.

Time to first production payment

Useful launch milestone.

Time to production readiness

Measures the controlled integration.

Time to financially reconciled production readiness

Measures whether the merchant can operate both the technical and financial lifecycle.

They answer different questions.

Measure the integration after launch too

A payment integration that launched quickly and creates incidents for the next year was not necessarily fast in any commercially meaningful sense.

Useful post-launch metrics include:

Post-launch defect rate

How much important integration behavior escaped testing?

Unknown-state rate

How many attempts remain without confirmed outcomes beyond the merchant-defined interval?

Manual reconciliation exceptions

How often does Finance need manual investigation?

Duplicate-payment rate

How often does one intended payment produce unintended multiple financial outcomes?

Maintenance burden

How much engineering/operations effort does the integration consume over time?

The brief explicitly frames financial correctness—not API uptime alone—as the relevant engineering objective.

Launch is not the end of the integration

Payment integrations change.

Dependencies can include:

API versions;

SDK versions;

webhook schemas;

certificates;

secrets;

domains;

browser behavior;

mobile operating systems;

wallet configuration;

payment methods;

authentication requirements;

provider notices;

rate limits;

reconciliation behavior.

The integration therefore needs a permanent owner.

This is the boundary between:

launch

and:

maintainability.

A production integration with no version inventory, maintenance owner, alerts, runbook, or upgrade process has moved work into the future rather than completed it.

Security belongs on the critical path

Payment architecture can affect:

payment-account-data handling;

tokenization;

credentials;

secrets;

encryption;

third-party service responsibilities.

Security review should therefore be planned rather than appended immediately before launch.

PCI SSC currently identifies PCI DSS v4.0.1 within its active/current v4.x standards materials. Exact applicability and validation responsibilities depend on the merchant architecture and should be assessed with qualified specialists rather than inferred from the fact that a PSP is involved.

Using a provider does not, by itself, establish that every merchant security responsibility has disappeared.

For Checkout API, the documented flow includes payment-page creation, payment-method selection, a server-side Pingback, client-side callback and customer redirect.

Its project-review documentation distinguishes test availability from the reviewed state required to begin accepting real payments.

And its Reporting API provides programmatic transaction-report access for merchant accounts where that API has been activated.

The defensible commercial message is therefore:

Do not turn that into:

The public documentation reviewed here does not establish a universal integration-time promise, and the brief explicitly prohibits inventing one.