Payment Gateway Development: Architecture & Integration Guide

A payment gateway is the software layer that authorizes, encrypts, and routes card transactions between a merchant, the acquiring bank, the card network, and the issuing bank. It also handles tokenization, fraud screening, and 3D Secure authentication along the way. That definition is short. The implementation is not.

This guide is for CTOs and engineering leads who already know they need a payment flow and now have to decide how to build it. The real question is rarely “which gateway is best.” It is built, integrated, or orchestrated, and the answer turns on the architecture decisions you make in the first two weeks.

We have shipped payment-adjacent platforms for US lenders, wealth managers, and neobanks (including engagements with Origence, a US wealth management platform, and a US personal loan platform with twenty senior engineers over three-plus years), and the patterns below are the ones that survived production.

How a Payment Gateway Actually Works

A payment gateway works in five hops:

1. The client tokenizes the card so the merchant never holds raw card data.

2. The gateway authorizes the transaction with the processor.

3. The processor routes through the card network to the issuing bank.

4. The issuer approves or declines.

5. The result returns to the merchant, often asynchronously through webhooks, which is where most production bugs hide.

The actors, briefly

Six entities matter:

• The merchant initiates the charge from the checkout page.

• The payment gateway handles authorization, tokenization, and routing.

• The payment processor handles settlement and the actual movement of funds.

• The acquirer is the merchant’s bank.

• The card network (Visa, Mastercard, Amex, Discover) carries the authorization message; the ACH network carries US bank-to-bank movements for use cases like payouts and some recurring payments.

• The issuer is the cardholder’s bank, and it has the final word on every authorization.

Most teams conflate gateway and processor. They are different. A gateway can talk to multiple processors. A processor can sit behind multiple gateways. Stripe, PayPal, and Adyen are commonly described as gateways, but each also operates as the processor in their stack, which is why their developer surface looks unified.

Learn more: Understanding ERC20 Tokens: The Backbone of Tokenized Economies

Synchronous versus asynchronous transaction flow

Synchronous model. Returns the auth result inline. The HTTP call blocks until the issuer responds. It is the simpler design, and it works for low-volume merchants on a single market.

Asynchronous model. Returns a 202 immediately, then delivers the downstream state through webhooks. It is harder to test, harder to recover from partial failures, and required for any platform that does recurring payments, marketplace splits, or expects more than a handful of transactions per second.

Settlement events arrive minutes to hours after authorization, and any system that treats them as a single sync call will eventually double-charge, double-refund, or lose track of disputed transactions.

Architecture diagram #1: end-to-end transaction flow

(Asset to render in publish: a sequence diagram with seven swimlanes, from Client through Merchant Backend, Gateway, Processor, Card Network, Issuer ACS, and Issuer. Show tokenization at the client, the 3DS2 challenge branch as a dotted side path, the webhook return, and the idempotency key as an annotation on the auth call. Alt text: End-to-end payment gateway development architecture: client tokenization through issuer authorization.) 

Field note (US lending platform engagement). The team chose async webhook-driven reconciliation over synchronous calls because settlement events arrive on a different timeline than auth responses. Conflating the two had previously caused duplicate disbursements during retry storms in pre-prod load testing.

The fix was structural, not a patch: every state transition in the merchant ledger had to be webhook-driven, and the auth response was treated as a hint, not a source of truth.

Build, Integrate, or Hybrid: The Three Real Options

Building a payment gateway from scratch is the wrong call for almost every team. The realistic options are three:

1. Integrate a single provider directly.

2. Build an orchestration layer over multiple providers.

3. Run a hybrid where a thin in-house layer routes to providers and owns merchant-side logic.

The decision turns on region count, acquirer strategy, and how much PCI-DSS scope you can tolerate.

When direct integration is the right call

For a single-market launch, with a single currency, an MVP rollout, or revenue under roughly fifty million in ARR, direct integration is almost always correct.

• PCI-DSS scope drops from SAQ-D to SAQ-A because the card data never touches your servers in cleartext.

• Time to market is measured in weeks.

• The provider handles scheme certifications, tokenization vault, and most of the fraud-heavy lifting.

The trade-off is lock-in. If your business case later requires multi-acquirer routing or per-region cost optimization, the migration cost is real. That cost is still smaller than building it up front.

When orchestration starts paying off

Orchestration becomes worthwhile when:

• Authorization rates differ meaningfully across regions.

• Fees from a single processor erode unit economics at scale.

• Marketplace splits across many sub-merchants make a single provider’s tooling insufficient.

The cost is six to twelve months of engineering for the first production-ready release, plus ongoing reconciliation complexity. Orchestration is not a side project. Most teams that try to develop a payment gateway orchestration layer as a sprint underestimate it by a factor of three.

Hybrid in practice

The hybrid pattern keeps the orchestration thin.

• The in-house layer owns: idempotency, the merchant ledger, reconciliation logic, fraud rules that span providers, and retry behavior.

• The providers own: the card vault, network connectivity, scheme certifications, and SCA flows.

This split keeps PCI scope manageable (typically SAQ-A-EP) and avoids the worst of the build-from-scratch trap.

Comparison table #1: build vs. integrate vs. hybrid

Numbers are typically ranges from real engagements. They vary by scope, vertical, and team rates. 

Integration Patterns for Stripe, PayPal, and Adyen

Stripe, PayPal, and Adyen solve overlapping problems with different developer surfaces. Each exposes its capabilities through public integration APIs, but the shape of the external API, the naming conventions, and the operational assumptions differ enough that swapping providers is a project, not a config change.

• Stripe optimizes for fast SCA-compliant integration through Payment Intents.

• PayPal (with Braintree) is strongest for marketplaces and PayPal-wallet acceptance.

• Adyen targets enterprise multi-region with native multi-acquirer routing.

The choice is rarely about feature parity. It is about which surface fits your operating model.

Learn more: Prototype Design Pattern in Java

Stripe: the Payment Intents pattern

Stripe’s Payment Intents API runs a state machine:

requires_payment_method → requires_confirmation → requires_action (if 3DS2 challenges) → succeeded (or a terminal failure) 

The SDK handles SCA by default. Webhook events drive the merchant-side state.

• Fits: SaaS, subscription products with recurring payments, and single-region first launches.

• Why it matters: the developer experience is the strongest of the three, which matters more than most architecture reviews acknowledge. A team that ships in six weeks and iterates beats a team that ships in six months with the theoretically better stack.

• Watch out: Radar, Stripe’s fraud engine. Its rules apply globally by default. Once you expand to a second region, you almost always need region-specific tuning, and that tuning is a steady-state job, not a one-time setup.

PayPal and Braintree: the Orders v2 pattern

PayPal’s Orders v2 API runs an Order to Capture flow, with vault tokens for repeat payers. Braintree, owned by PayPal, exposes a more developer-friendly surface for card and wallet acceptance.

• Fits: marketplaces, payouts, and any product where a meaningful fraction of buyers pay with the PayPal wallet. For consumer marketplaces in the US and EU, that fraction is high enough to make PayPal the default secondary method even when cards are primary.

• Watch out: the dispute lifecycle. PayPal disputes work differently from card chargebacks, with different timelines, evidence formats, and resolution paths. Engineer the reconciliation around it from day one. Retrofitting it after the first batch of disputes is painful.

Adyen: the unified commerce pattern

Adyen exposes one API across cards, wallets, and local payment methods such as iDEAL, Bancontact, and GrabPay. Multi-acquirer routing is native, not bolted on. Settlement reporting is the strongest of the three for finance teams that want a single ledger across markets.

• Fits: enterprise, multi-region, brick-and-click retail, and any platform with serious volume across more than two countries.

• Watch out: configuration overhead. Onboarding takes longer than Stripe. The documentation assumes you know what you want. There is less hand-holding, which is fine for a team with payments experience and frustrating for a team picking up payments for the first time.

How to choose between them

A short decision lens, in order of weight:

Comparison table #2: feature parity matrix

Fees vary by volume, region, and merchant category code. Treat tiers as directional and request a quote at your expected volume. 

Field note (US wealth management platform engagement). On a multi-year build with the team handling portfolio, trading, and fund operations, we paired one provider for US card acceptance with a second for selected APAC corridors. The reason was authorization-rate differences across regions, which compounded to meaningful revenue at platform volume.

The directional figure we observed was a four-to-seven-point spread between providers in some corridors, which is consistent with publicly reported acquirer-routing benchmarks but varies sharply by merchant category and BIN mix. Treat that range as illustrative, not a benchmark to plan against.

Security Layers Every Production Gateway Needs

Production payment gateway security rests on three layers:

1. Tokenization keeps card data out of your systems.

2. 3D Secure 2 shifts authentication and liability to the issuer.

3. PCI-DSS scope reduction keeps audit overhead manageable.

Skipping any one of them creates compounding compliance and fraud costs, and the costs are not linear.

1. Tokenization: vault tokens versus network tokens

Vault token (provider-issued). Binds to one ecosystem. Works inside Stripe’s stack but not Adyen’s, and vice versa. Fine for single-provider integrations.

Network token (issued by the card network itself: Visa, Mastercard, Amex). Survives card reissuance. When a customer’s card is replaced (lost, expired, fraud reissue), the network token continues to work, and authorization rates measurably improve.

Network tokenization is now table stakes for any platform with recurring billing or card-on-file logic. Tokenization replaces the card data with a non-sensitive reference; encryption (TLS in transit, AES at rest for any token-to-customer mapping you do hold) protects the rest of the payload around it.

Practical impact: if the iframe or SDK ensures that the raw primary account number never touches your origin server, your PCI-DSS scope drops from SAQ-D to SAQ-A. That is the difference between a months-long audit cycle and a self-attestation.

2. 3D Secure 2: frictionless versus challenge

A 3DS2 transaction either passes:

• Frictionlessly (the issuer accepts based on risk score and device data, with no user interaction). The frictionless path is invisible.

• Via challenge (biometric, OTP, or app-based confirmation). Adds friction, but it shifts liability from the merchant to the issuer.

PSD2 SCA exemptions matter here. Low-value transactions, recurring transactions after the first, merchant-initiated transactions, and Transaction Risk Analysis exemptions can all keep transactions on the frictionless path. Use them deliberately. Letting every transaction default to challenge will visibly hurt conversion.

3. Architecture diagram #2: 3DS2 sequence

(Asset to render: a sequence diagram with six lanes, from Cardholder through Merchant, Gateway, 3DS Server, Directory Server, and Issuer ACS. Show device data collection, the frictionless branch in green, the challenge branch in amber, and a liability-shift annotation. Alt text: 3DS2 authentication sequence in payment gateway integration.)

4. PCI-DSS scope reduction patterns

The goal of scope reduction is to minimize the systems that handle cardholder data, which in turn minimizes audit cost.

Scope-reducing patterns, from least to most invasive UX:

• Hosted fields (provider-rendered inputs inside your page).

• Redirect flows (full handoff to provider).

• iframes (sandboxed payment UI).

• SDK-based tokenization (mobile and web).

Choose the least invasive UX that keeps you compliant.

On HSMs. Hardware Security Modules are sometimes proposed as the answer to PCI compliance. They are necessary only if you genuinely store cleartext card data, which is rare and increasingly avoidable. For most modern integrations, a cloud KMS for non-PAN secrets and provider tokenization for cards is the right architecture.

5. Fraud signals beyond the card network

Network-level fraud screening is necessary but not sufficient. Production fraud stacks layer on:

• Device fingerprinting

• Velocity rules (per card, per IP, per device, per email)

• BIN-country mismatch detection

• Behavioral biometrics

• ML scoring

These sit alongside the infrastructure controls every payment-handling system needs anyway: web-application firewalls, DDoS protection at the edge, and authorization controls (least-privilege roles, per-service tokens) on every internal service that can touch a token or a transaction record.

The trade-off is real. Aggressive rules cut fraud, and they also cut good transactions. The metric to watch is not just fraud rate. It is fraud rate plus false positives, weighted by the lifetime value of customers you turn away. Most teams underweight the false-positive cost in their first year and overweight it in their third.

For authoritative reference on PCI requirements, see the PCI Security Standards Council (PCI-DSS v4.0.1, effective March 2025). For 3DS2 specifications, EMVCo is the standards body.

What Production Reliability Actually Requires

A payment gateway integration that works in staging often fails in production not because of bugs, but because of duplicates, out-of-order webhooks, and reconciliation mismatches.

Idempotency, signed webhooks, and a merchant-side ledger are the three controls that prevent the most common production incidents. None of them are optional at scale.

Idempotency keys are not optional

Every charge attempt needs a client-generated idempotency key. The reasons are mundane and ubiquitous:

• Network retries

• Lambda re-invocations

• User-side double-clicks

• CI/CD redeploys that re-fire pending requests

Without idempotency, each of these silently double-charges.

The pattern is straightforward:

1. Persist the idempotency key plus the result of the first attempt before responding.

2. On any subsequent attempt with the same key, return the original result.

The provider handles the same logic on their side, but you cannot rely on theirs alone, because your retry path might fire before their replay logic engages.

Webhook handling done right

Four rules handle the majority of webhook bugs we see in production:

1. Verify the signature on the raw request body before parsing. Most signature failures happen because a middleware parsed the body first and changed the byte sequence. The HMAC verification has to happen on the exact bytes the provider signed.

2. Build replay protection. A timestamp plus a nonce, with a short window of acceptable timestamps, blocks most replay attacks. Providers signed the timestamp into the signature for a reason.

3. Design for at-least-once delivery. Providers retry webhooks on failures, and they sometimes deliver out of order. Your event handler has to be idempotent, not just your charge call.

4. Expect events to arrive in surprising orders. A payment_intent.succeeded event can arrive before the charge.succeeded event in some retry scenarios. The merchant-side state machine has to tolerate that without corrupting the ledger.

Reconciliation and chargebacks

Daily settlement files do not always match the webhook history. Both are correct, but they are not the same thing. A clean architecture maintains a three-way match:

• Provider events

• Merchant ledger

• Settlement file

Where the three disagree, the merchant ledger is usually wrong, and the fix is rarely fast.

Chargebacks are the other production reality. Build the dispute response workflow on day one. The window to respond is short (often seven to twenty days, depending on the network and reason code), and the evidence requirements are specific. Teams that wait for the first chargeback to design the workflow lose the dispute by default.

Field note (US lending platform pre-prod load test). An idempotency-key replay test caught a subtle duplicate-disbursement path. A webhook retry, combined with a manual reconciliation script that ran on a cron, could fire the same payout twice under specific timing conditions.

The fix landed before launch, and the bug would have been invisible in normal staging traffic. That kind of test is the difference between a clean go-live and a postmortem.

Compliance Beyond PCI: Regional Realities

PCI-DSS is necessary but not sufficient.

• EU operations need PSD2 SCA.

• India needs RBI tokenization compliance.

• US operations interact with state-level money-transmission rules.

Regional compliance shapes architecture more than most teams expect when scoping a payment gateway development project, and the cost of retrofitting it is high.

1. PCI-DSS v4.0.1

The current standard (effective March 2025) raised the bar in a few specific places:

• Multi-factor authentication is required for all personnel access to cardholder data environments, and the MFA must be phishing-resistant.

• Continuous monitoring requirements expanded.

• Targeted Risk Analyses now apply where compensating controls are used.

None of these are surprises if you have run a PCI program before. All of them are work to retrofit if you have not.

2. PSD2 and SCA in the EU and UK

Strong Customer Authentication applies to most in-scope transactions in the EU and UK. The 3DS2 flow handles it. The exemption logic, applied correctly, keeps friction off transactions that qualify. Applied incorrectly, exemption logic creates auth-rate cliffs that are hard to debug after the fact.

3. RBI tokenization in India

The Reserve Bank of India’s tokenization mandate makes card-on-file tokenization mandatory for any platform serving Indian cardholders. This affects card storage architecture for any global platform, not just India-first ones. The compliance window has passed; non-compliance is a now problem.

4. US state-level money transmission

If your platform holds or moves customer funds (rather than passing them straight through), state-level money-transmitter licenses can apply.

The architectural choice is between using a sponsor bank or a banking-as-a-service partner versus building licensure in-house. Most teams pick the first, and the choice has implications for the data flow, the ledger model, and the contractual structure.

Money-transmitter scope also pulls KYC/AML obligations into the onboarding flow, which shapes how the merchant ledger and identity store are designed from day one.

Compliance disclaimer. Compliance requirements change. This section reflects standards as of May 2026. Consult qualified compliance counsel before finalizing architecture decisions for any regulated market.

When to Bring In a Fintech Engineering Partner

Most teams underestimate the steady-state engineering load of payment gateway software development at production scale.

If your in-house team:

• Has fewer than five backend engineers, or

• Lacks PCI-DSS audit experience, or

• Is launching in a regulated market for the first time

…partnering with a specialist accelerates without sacrificing ownership. The build-yourself instinct is correct only when your core IP is the gateway itself.

Capability checklist for evaluating a partner

• ✅ ISO 27001 (information security) and ISO 9001 (quality management) certifications, as a minimum bar for handling card-adjacent systems

• ✅ Documented PCI-DSS audit experience on prior engagements

• ✅ Engineering depth across .NET, Node, Java, and Python (most fintech stacks are mixed)

• ✅ A team shape that fits payment work: a solution architect, backend payment gateway developers, DevOps engineers, QA engineers, and a project manager who has shipped a regulated integration before

• ✅ Real project references in your specific sub-vertical: lending, wealth management, neobank, or marketplace

• ✅ Twenty-four-hour incident response capability with on-call rotation

• ✅ Clear IP-transfer terms, NDAs, and complete ownership transfer at the end of the engagement

Saigon Technology has shipped payment-adjacent platforms for US lenders, wealth managers, and neobanks under PCI-DSS-aligned controls, including the wealth management platform referenced earlier in this file and lending engagements with named US clients such as Origence.

The work spans full-stack architecture, security, and reconciliation, and the engagement models we have seen succeed are dedicated team and offshore development center, where the partner team integrates into the client’s product cadence rather than running a parallel sprint cycle. For more on how we structure those engagements, see our work with specialized fintech engineering partners.

FAQs

1. How long does payment gateway development take?

• Direct integration with Stripe, PayPal, or Adyen typically ships in four to twelve weeks for a single market.

• Hybrid orchestration layer over multiple providers takes four to nine months for a production-ready first release.

• Building a gateway from scratch (rarely the right call outside of card networks themselves and the largest merchants) runs eighteen to thirty-six months and requires a steady-state team of fifteen or more engineers.

2. How much does it cost to build a payment gateway?

• Integration projects: roughly $40K–$200K depending on scope, fraud rule complexity, and reconciliation requirements.

• Hybrid orchestration: $300K–$1.5M for the first production-ready release.

These ranges are directional and vary by region, vertical, team rates, and the depth of compliance work required.

3. Stripe versus Adyen for B2B SaaS?

Stripe ships faster and has stronger developer experience for single-region launches. Adyen wins once you need multi-acquirer routing across regions or want enterprise-grade settlement reporting against a single ledger.

For most B2B SaaS under twenty million in ARR, Stripe is the right starting point. Migration to Adyen, or running both alongside each other, comes later if it is needed at all.

4. Do I need to be PCI-DSS compliant if I use Stripe?

Yes. Using Stripe reduces your scope, often to SAQ-A, but it does not eliminate it.

You are still responsible for:

• Ensuring card data never touches your servers in cleartext

• Maintaining the security controls around the systems that interact with the gateway

• Completing the appropriate Self-Assessment Questionnaire annually

Provider integration changes the scope, not the obligation.

Closing

The hardest decision in payment gateway development is the first one: integrate, orchestrate, or hybrid. Region count, acquirer strategy, and PCI scope tolerance settle it more reliably than feature comparisons between providers.

Most teams should integrate first, instrument well, and only orchestrate when the unit economics or regional realities force it.

For deeper context on how Saigon Technology approaches fintech engineering across lending, wealth management, and payments, explore our fintech industry practice or get in touch.