Building a payment gateway means building the system that securely captures payment details, tokenizes them, runs fraud and authentication checks, routes authorization requests to acquirers or payment processors, handles captures, refunds and chargebacks, and reconciles settlements to a ledger. The core components are a checkout layer, a gateway API, a token vault in an isolated cardholder data environment, a risk and 3-D Secure service, acquirer connectors, a ledger and reconciliation, and merchant tools. Any system that stores, processes or transmits card data must comply with PCI DSS, so most of the architecture is about keeping card data in as small a part of the system as possible. Before building, check whether integrating existing processors behind your own orchestration layer would meet the need at far lower cost and risk.
Key takeaways
- Decide first whether you need a full gateway or a payment orchestration layer.
- Isolate card data in a small, separately secured environment and tokenize everything else.
- PCI DSS assessment, acquirer agreements and scheme rules shape the timeline.
- Idempotency, a double-entry ledger and reconciliation prevent money errors.
- Design for high availability, because payment downtime is lost revenue.
Should you build a payment gateway?
| Option | What you build | Fits when |
|---|---|---|
| Use a payment provider | Integration only | You simply need to accept payments |
| Payment orchestration layer | Routing, retries, tokens via providers, reporting | You use several providers and want control and resilience |
| Own gateway with acquirer connections | Full stack, including cardholder data environment | Payments are your product, or volume and margins justify it |
The third option brings direct PCI DSS obligations, acquirer and scheme relationships, and continuous security operations. Many companies get most of the benefit from the second.
How a card payment flows
Authorization reserves funds; capture requests the money; settlement moves it to the merchant, usually in batches; refunds and chargebacks reverse it. The gateway tracks each payment as a state machine across these steps.
Payment gateway architecture
- Checkout: hosted fields or a hosted page so card data goes straight to the vault, not through merchant systems.
- Gateway API: authenticated, versioned, idempotent endpoints for payments, captures and refunds.
- Token vault: stores encrypted card data with keys in hardware security modules; returns tokens to the rest of the system.
- Risk and authentication: fraud rules and models, and EMV 3-D Secure for cardholder authentication; see AI fraud detection for payments.
- Acquirer connectors: adapters for each acquirer or processor, with routing and failover.
- Ledger and reconciliation: double-entry records of every movement, matched to settlement files.
- Merchant tools: dashboard, reporting, webhooks and dispute handling.
PCI DSS and security
The PCI Data Security Standard applies to any entity that stores, processes or transmits cardholder data. A gateway operating its own vault is typically assessed as a service provider by a qualified security assessor. Architecture choices reduce the scope of that assessment:
- Network segmentation so only the vault and a few services touch card data.
- Tokenization everywhere else, with no card numbers in logs, analytics or support tools.
- Strong encryption, key management in HSMs and strict access control.
- Secure development, vulnerability management, logging and monitoring.
This article is technical guidance, not compliance or legal advice; scope and requirements must be confirmed with a qualified security assessor and your acquirer. For hosting considerations, see choosing a cloud provider for FinTech.
Reliability and correctness
- Idempotency keys on every request; see idempotency in distributed systems.
- Explicit state machines for payments, with safe handling of timeouts and unknown outcomes.
- Multi-step consistency without distributed locks; see saga pattern vs two-phase commit.
- Webhooks to merchants with signatures and retries; see webhook vs polling vs event streaming.
- High availability: multi-zone deployment, acquirer failover and tested recovery.
- Testing: contract and integration tests for every connector; see microservices testing strategies.
Steps to build a payment gateway
- Define payment methods, markets, volumes and the build option.
- Engage acquirers or processors and a PCI assessor early.
- Design the cardholder data environment and tokenization.
- Build the gateway API, payment state machine and ledger.
- Integrate acquirers, 3-D Secure and fraud checks.
- Build merchant tools, webhooks and reconciliation.
- Complete security testing, certification with acquirers and PCI assessment.
- Launch gradually with monitoring and on-call support.
For the wider API landscape, see FinTech APIs explained.
Common questions
What is a payment gateway?
A system that securely captures payment details and routes transactions between a merchant, acquirers or processors and card networks, returning the result.
Is it worth building your own payment gateway?
Only if payments are core to your product or your volume justifies it. Otherwise, a provider or an orchestration layer over providers is usually better.
Does a payment gateway need PCI DSS compliance?
Yes, if it stores, processes or transmits cardholder data. The level and scope depend on your role and volumes and must be confirmed with an assessor.
How long does it take to build a payment gateway?
An orchestration layer can take a few months. A full gateway with its own vault, acquirer certifications and PCI assessment commonly takes a year or more.
What is tokenization in payments?
Replacing card details with a token that is useless outside the system, so most components never handle real card data.
Design your payment platform
Our API and system integration and software development teams design payment orchestration layers, ledgers and gateway architectures, working alongside your acquirers and security assessors.