Payment Gateway Integration: Scope, Timeline, and Hidden Dependencies
Oct 18, 2026 · @Kevin Medina
A gateway integration is more than calling an API. Scope it by the transaction lifecycle you must support, the environments and approvals you need, and the operations around the money: settlement and reconciliation. The API calls are often the smallest part. Timelines depend on processor onboarding, credentials, test environments, and any certification, and a developer controls few of those.
This guide maps the lifecycle, lists the dependencies that slow projects down, and covers the engineering details that prevent expensive surprises.
Map the transaction lifecycle
Terms vary between processors, so use your processor's definitions. This table shows the operations most projects must scope.
| Operation | What it does | What to define |
|---|---|---|
| Authorization | Requests approval and may hold funds | Amount, currency, entry mode, response code handling |
| Capture | Collects funds from an earlier authorization | Timing, partial capture support |
| Void | Cancels before settlement | Time window and who can trigger it |
| Refund | Returns funds after settlement | Full or partial, linked or unlinked |
| Reversal | Undoes a transaction when the outcome is uncertain | Triggers, timeouts, retry rules |
| Settlement | Moves funds in batches | Batch timing and cutoffs |
| Reconciliation | Matches your records to processor and bank data | Report formats and exception handling |
Card-present and card-not-present
Card-present integrations involve a reader or terminal, EMV processing, and often certification with the processor. Card-not-present integrations use APIs, hosted fields, or tokenization, and PCI scope depends on whether card data touches your systems. They share a lifecycle but have different dependencies, so scope them separately.
To decide whether to build, white label, or buy a gateway, see Gateways: To Build, White Label, or Buy. For picking a partner, see Choosing the Right Payment Integration Partner.
Hidden dependencies
| Dependency | Why it matters | Usually owned by |
|---|---|---|
| Credentials and merchant IDs | Testing cannot start without them | Processor and you |
| Specs and sandbox access | Accurate tests need current documentation | Processor |
| Separate environments | Test, certification, and production often use different keys and URLs | Processor |
| Processor testing or approval | Some processors require test evidence before production | Processor and you |
| Network rules | IP allow lists and firewall changes | You and processor |
| PCI scope decisions | Where card data flows affects your obligations | You |
| Reporting access | Needed for reconciliation | Processor |
Timelines vary widely. Treat any single number as a guess until you have the processor's onboarding details.
Milestones and responsibilities
| Milestone | Output | Leads |
|---|---|---|
| Scope the lifecycle | Transaction matrix and exclusions | Engineering and business |
| Credentials and sandbox | Working test calls | Processor and you |
| Core integration | Authorize, capture, void, refund in sandbox | Engineering |
| Failure handling | Timeouts, retries, idempotency | Engineering |
| Webhooks and reconciliation | Event handling and reports | Engineering and finance |
| Processor testing | Test evidence and approval | Engineering and processor |
| Pilot and rollout | Limited live traffic with monitoring | Joint |
Engineering details that matter
▸ Webhooks: verify signatures, expect retries and duplicate events, and do not rely on delivery order.
▸ Idempotency: use idempotency keys or your own unique transaction IDs where the gateway supports them, so a retry cannot charge twice.
▸ Security: keep secrets out of code, use TLS, limit access, and keep card data out of logs.
▸ Testing: cover declines, timeouts, duplicate requests, and partial failures using sandbox and test data only.
▸ Rollout: use feature flags, start with a small cohort, monitor errors and approval rates, and keep a rollback path.
FAQs
How long does a gateway integration take?
It depends on the processor's onboarding, the lifecycle you support, and whether certification is needed. Get the processor's requirements before committing to dates.
Do I need to support refunds and reversals on day one?
Usually yes for anything live. Decide up front which operations are in scope and which are deferred.
What is the most common hidden delay?
Waiting on credentials, sandbox access, or processor approval, which sit outside engineering.
Do webhooks replace polling?
Not always. Many designs use both, with webhooks for speed and a reconciliation job to catch what was missed.
Next step
If you can share your processor, hardware or software stack, and the transaction types you need, we can help scope the integration and flag the dependencies early. Start at the integration page.
Sources
▸ Gateways: To Build, White Label, or Buy
Software executive with over three decades of experience. Focus primarily on the payment industry and FinTech technologies
