What you actually need to build a payment gateway
A payment gateway is software that sits between a customer, a merchant, and the banks or card networks involved. It encrypts card data, routes transactions to the right processor, handles the response, and tells the merchant whether the charge went through. Building one means writing code to handle encryption, PCI compliance, API connections to multiple processors, fraud detection, settlement logic, and reconciliation—all of which have to work 24/7 without losing a single transaction.
Most businesses do not build their own gateway from scratch. The cost is high, the liability is real, and the regulatory burden is heavy. But if you are building one—either as a standalone product or as part of a larger platform—you need to understand the layers involved, the connections you have to make, and the compliance requirements that will slow you down.
Key Takeaways
- A payment gateway needs to connect to at least one payment processor, which handles the actual bank communication and settlement.
- PCI DSS compliance is mandatory if you touch card data, and the compliance level depends on how many transactions you process annually.
- You will need to integrate with card networks (Visa, Mastercard, American Express, Discover), acquiring banks, and issuing banks through a processor.
- Building fraud detection, tokenization, and retry logic into your gateway from the start saves you from rebuilding it later when chargebacks spike.
- Most payment gateways take 12 to 24 months to build and launch, and ongoing maintenance and regulatory updates never stop.
The core architecture: what your gateway has to do
Your gateway receives a transaction request from a merchant's website or app. That request contains card data, amount, currency, and metadata about the order. Your code has to validate the request, encrypt the card data immediately, and pass it to a payment processor—never storing the raw card number yourself.
The processor sends the transaction to the card network (Visa, Mastercard, etc.), which routes it to the customer's bank. The bank approves or declines. The processor sends the response back to your gateway. Your gateway logs the result, returns a response code to the merchant, and stores a token or reference ID for later settlement and reconciliation.
This entire flow has to happen in under three seconds, and it has to work even when one of the upstream systems is slow or temporarily down. You need retry logic, timeout handling, and a queue system to manage transactions that fail on the first attempt. You also need to log every step for compliance audits and dispute resolution.
Processor connections and the acquiring bank relationship
You cannot connect directly to Visa or Mastercard. You connect to a payment processor—a company like Stripe, Square, Adyen, or a regional processor—which has already done the work of connecting to the card networks and acquiring banks. The processor provides you with an API, documentation, and a sandbox environment for testing.
Each processor has its own API format, error codes, and settlement rules. If you want to support multiple processors (which you should, for redundancy and merchant choice), you have to write an abstraction layer that translates your internal transaction format into each processor's format, then translates their responses back into your format.
You also need a relationship with an acquiring bank—the bank that holds the merchant's settlement account and deposits funds after transactions clear. Some processors own their acquiring bank license; others partner with one. Either way, you need to understand the settlement timeline (usually one to three business days), the fee structure, and the chargeback process.
PCI compliance and data security
PCI DSS (Payment Card Industry Data Security Standard) is a set of 12 requirements that apply to anyone who handles card data. The compliance level depends on how many transactions you process per year. Level 1 (over 6 million transactions annually) requires a full audit by a may have access to security assessor. Levels 2–4 allow self-assessment, but the work is still substantial.
The core rule: never store raw card data. Use tokenization—replace the card number with a unique token that only your processor can decrypt. Your gateway stores the token, not the card. When you need to charge the card again, you send the token to the processor, which decrypts it and processes the charge.
You also need encryption in transit (TLS 1.2 or higher), encryption at rest for any data you do store, regular security audits, a vulnerability disclosure policy, and employee training. You need to log access to sensitive data and monitor for suspicious activity. All of this has to be documented and auditable.
Fraud detection and chargeback management
Fraud detection starts with basic checks: does the card number pass the Luhn algorithm? Does the CVV match the card type? Is the transaction amount reasonable for this merchant? But real fraud is more subtle. A customer might use a stolen card for a small purchase to test it, then make a large purchase later. A bot might try hundreds of card numbers in seconds.
Most gateways use a combination of rule-based checks (velocity limits, geographic mismatches, unusual amounts) and machine learning models trained on historical fraud data. You can build your own, but most teams license fraud detection from a third party like Kount, Sift, or Forter and integrate it into your gateway.
When a customer disputes a charge, the issuing bank initiates a chargeback. The processor notifies you, and you have a window (usually 7 to 10 days) to respond with evidence that the transaction was legitimate. Your gateway needs to store transaction details, customer communication, and shipping or delivery proof so you can respond quickly. Chargebacks are expensive—the processor charges a fee, and if your chargeback rate exceeds a threshold (usually 0.5% to 1%), you face penalties or losing your processor relationship.
Settlement, reconciliation, and reporting
Settlement is the process of moving money from the card networks to the acquiring bank to the merchant's account. It does not happen instantly. A transaction approved at 2 p.m. on Tuesday might not settle until Thursday morning. During that window, the transaction is in a pending state.
Your gateway needs to track the status of every transaction: authorized, captured, settled, failed, or refunded. You need to match transactions you processed against the settlement file the processor sends you each day. This is reconciliation, and it is tedious but critical. If a transaction appears in your records but not in the settlement file, you need to investigate why.
You also need to handle refunds, partial captures, and voids. A void cancels a transaction before it settles. A refund returns money after settlement. Each has different rules and timelines. Your gateway needs to support all of these operations and report on them clearly so merchants can see what happened to their money.
Testing, launch, and ongoing maintenance
Before you launch, you need to test in the processor's sandbox environment. You test happy paths (successful transactions), error paths (declined cards, timeouts, invalid data), edge cases (zero-dollar transactions, currency conversions, recurring charges), and load (can your system handle 1,000 transactions per second?). You test with multiple processors if you support more than one.
You also need to pass a PCI audit before you go live. This is not a one-time event. You need an annual audit, and you need to respond to any findings. You need to maintain your compliance posture continuously—updating libraries, patching vulnerabilities, rotating credentials, and monitoring access logs.
After launch, you will spend time on customer support (merchants with integration questions), processor relationship management (staying informed of API changes), regulatory updates (new PCI requirements, new payment methods), and incident response (when a processor goes down or a security issue emerges). Payment gateways are not a build-once product.
Frequently Asked Questions
Do I have to build my own gateway, or can I just use an existing one?
Most businesses use an existing gateway. Building one makes sense only if you have millions of transactions annually, need custom logic that no existing gateway offers, or are building a platform (like a marketplace or SaaS product) that needs payment processing built in. The cost and complexity are high enough that using an existing processor is usually the right choice.
What is the difference between a payment gateway and a payment processor?
A gateway is the software that accepts a transaction request and routes it to a processor. A processor is the company that connects to the card networks and banks. Some companies (like Stripe) provide both. If you are building a gateway, you will use an existing processor's API to handle the actual payment processing.
How long does it take to build a payment gateway?
A basic gateway that handles credit cards and connects to one processor typically takes 6 to 12 months. Adding support for multiple processors, alternative payment methods (ACH, digital wallets), recurring billing, and full PCI compliance can stretch that to 18 to 24 months or longer. Ongoing maintenance and updates continue indefinitely.
What happens if my gateway loses a transaction?
This is why logging and reconciliation matter. Every transaction should be logged to a database before you send it to the processor. If the processor never receives it, you know because it will not appear in the settlement file. If the processor receives it but your gateway crashes before storing the response, you can query the processor's API to find out what happened. The key is never losing the record.
Can I avoid PCI compliance by using tokenization?
Tokenization reduces your PCI burden significantly, but it does not eliminate it. You still need to comply with PCI DSS requirements around access control, encryption, monitoring, and incident response. The compliance level depends on how you handle the token and what other data you store. Most teams find that using a hosted payment form (where the processor handles tokenization) is simpler than building tokenization themselves.