What you need to build a payment gateway
A payment gateway is software that sits between a customer's bank and your business account, taking payment information from one side and sending it to the other in a format both understand. Building one means writing code to handle that translation, connecting to the networks that move money (Visa, Mastercard, ACH), and storing sensitive data in a way that doesn't get you sued or hacked.
You need four things: a team with software engineers who understand cryptography and network protocols, a connection to at least one payment processor (the company that actually talks to the banks), a way to store card data that meets PCI DSS standards (the security rules the card networks enforce), and money to pay for the infrastructure and the legal review that comes before you go live.
Most businesses do not build their own gateway. They use one that already exists—Stripe, Square, PayPal—because the cost and complexity of building one correctly is high. But if you are building one anyway, you need to understand what the gateway actually does at each step, because that determines what you have to build.
Key Takeaways
- A payment gateway translates payment information from your customer into a format the banking networks understand, then sends the response back to your checkout page.
- You must connect to a payment processor, not directly to Visa or Mastercard—the processor handles the connection to the networks on your behalf.
- Card data cannot live on your servers; it must either be tokenized (replaced with a reference number) or sent directly to the processor without touching your system.
- PCI DSS compliance is mandatory if you handle card data, and the audit costs thousands of dollars per year even after you build the gateway.
- Building a gateway takes six to eighteen months with a team of at least three engineers, and you will need legal review before processing a single transaction.
How payment data actually moves through your gateway
When a customer enters their card number on your checkout page, your gateway receives that data and when ready sends it to your processor. The processor validates the card number using the Luhn algorithm (a math check that catches typos), then sends the full transaction to the card network—Visa, Mastercard, Discover, or American Express.
The card network routes the transaction to the customer's bank (the issuer). The issuer checks whether the account exists, whether it has enough money, whether the transaction matches the customer's spending patterns, and whether the card is reported stolen. The issuer sends back a response code: approved, declined, or needs more information.
That response travels back through the network to your processor, then to your gateway, then to your checkout page. The whole thing takes two to ten seconds. Your gateway displays the result to the customer—"Payment successful" or "Card declined"—and sends a confirmation to your backend so you know whether to ship the order or refund the customer.
If the transaction is approved, the money does not move when ready. The processor batches your transactions (usually once per day) and sends them to the networks for settlement. Settlement is when the money actually leaves the customer's bank account and arrives in your processor's account, which then deposits it into your business bank account. That takes one to three business days.
Connecting to a payment processor and the networks
You cannot connect directly to Visa or Mastercard. You must work through a payment processor—a company licensed to move money on behalf of merchants. The processor has already done the legal work and paid the fees to connect to the card networks. Your job is to connect to the processor.
The processor gives you API credentials (a username and password for your code) and documentation that describes how to send transaction data to their servers. You write code that takes the customer's payment information, formats it according to the processor's specification, and sends it over an encrypted connection (HTTPS with TLS 1.2 or higher). The processor's API responds with a transaction ID, a response code, and a timestamp.
You will need to connect to multiple processors if you want to accept multiple payment methods. ACH transfers (bank-to-bank payments) go through a different processor than card payments. International cards may require a different processor than domestic ones. Each connection is a separate integration, with its own API documentation and its own set of credentials.
The processor charges you per transaction—usually 2.2% to 3.5% of the transaction amount plus a flat fee of 20 to 30 cents. They also charge monthly fees for access to their API, monthly PCI compliance fees, and fees for chargebacks (when a customer disputes the charge and their bank reverses it). These fees are non-negotiable until you are processing millions of dollars per month.
Storing card data without breaking the law
Card data is regulated by the Payment Card Industry Data Security Standard, or PCI DSS. The standard is enforced by Visa, Mastercard, Discover, and American Express. If you store card data on your servers and you get hacked, you are liable for the cost of notifying customers, the cost of credit monitoring, and fines from the card networks that can reach $100,000 per month.
The safest approach is to never store card data at all. Instead, use tokenization: the customer's card number is sent directly from their browser to your processor, never touching your servers. The processor returns a token—a random string of characters that represents the card but is useless to a thief. You store the token in your database. When you need to charge the card again, you send the token to the processor, not the card number.
If you must store card data on your servers, you need to encrypt it using AES-256 encryption, store the encryption keys separately from the data (usually in a hardware security module), and pass a PCI DSS audit every year. The audit costs $5,000 to $15,000 per year and requires you to document every server, every network connection, every access log, and every change you made to your code. Most small businesses find this cost prohibitive and use tokenization instead.
You also need to handle PCI DSS compliance for your entire system, not just the card data. That means your servers must run updated operating systems, your code must be reviewed for security vulnerabilities, your team members must pass security training, and you must have a plan for responding to a breach. If you are processing fewer than 20,000 transactions per month, you can use a self-assessment questionnaire instead of a full audit, but you still have to answer detailed security questions and prove you meet the standard.
Building the code that handles transactions
Your gateway code needs to do several things in order. First, it validates the input: checking that the card number is the right length, that the expiration date is in the future, that the CVV is three or four digits. This happens on your server, not in the browser, because a customer can modify code in their browser.
Second, it sends the transaction to your processor. Your code constructs a request with the transaction amount, currency, card details (or token), customer details, and a unique reference number. It signs the request using a cryptographic key so the processor knows it came from you. It sends the request over HTTPS and waits for a response.
Third, it handles the response. The processor returns a status code (0 for approved, 1 for declined, 2 for error), a transaction ID, and a message. Your code checks the status, logs the transaction in your database, and either confirms the order or displays an error message to the customer.
Fourth, it handles edge cases. What happens if the processor's server is down? Your code should queue the transaction and retry it later. What happens if the customer closes their browser before the response arrives? Your code should check the processor's API to see whether the transaction went through. What happens if the same transaction is submitted twice by accident? Your code should use the unique reference number to detect duplicates and reject the second one.
Fifth, it reconciles with your processor. Once per day, you read a report from your processor showing which transactions settled, which ones failed, and which ones are still pending. Your code compares that report to your database and flags any mismatches so you can investigate.
The timeline and team you need
Building a payment gateway with a small team takes six to eighteen months. The first two months are spent on design and security planning—deciding which processor to use, which payment methods to support, how to handle errors, and how to meet PCI DSS requirements. The next three to six months are spent writing and testing the code. The next two to four months are spent on security audits, penetration testing, and legal review. The final month is spent on integration testing with your processor's sandbox environment (a test version of their API that does not move real money).
You need at least three engineers: one who specializes in backend systems and API integration, one who specializes in security and cryptography, and one who specializes in frontend code and user experience. You also need a product manager to decide what features to build first, a compliance officer to handle PCI DSS requirements, and a lawyer who understands payment regulations.
Before you go live, your processor will audit your code and your infrastructure. They will check that you are using HTTPS, that you are not storing card data, that you are handling errors correctly, and that you have a plan for responding to security incidents. This audit takes two to four weeks. If they find problems, you have to fix them before they will let you process transactions.
When to build your own versus using an existing gateway
Build your own gateway if you are processing more than $10 million per year and the fees from an existing gateway are costing you more than the cost of building and maintaining your own. At that scale, the per-transaction fees add up to hundreds of thousands of dollars per year, and building your own can save money.
Build your own if you need payment methods that existing gateways do not support—certain regional payment methods, cryptocurrency, or highly specialized transaction types. In that case, you are not replacing an existing gateway; you are building a specialized one that handles a specific use case.
Do not build your own if you are processing less than $10 million per year. The cost of building, maintaining, and auditing your own gateway will exceed the fees you pay to an existing one. Use Stripe, Square, PayPal, or another established processor instead. They have already done the security work, they handle PCI DSS compliance, and they can scale with you as you grow.
Frequently Asked Questions
Can I build a payment gateway without connecting to a processor?
No. You need a processor to connect to the card networks. You could theoretically build a gateway that only accepts one payment method (like ACH transfers through a single bank), but you would still need to connect to that bank's API. A true payment gateway that accepts multiple payment methods requires at least one processor.
What happens if my gateway goes down during a transaction?
If your gateway's servers are down, customers cannot submit payments. The processor's servers are separate, so if your servers are down but the processor is up, you are still losing transactions. You need redundancy: multiple servers in different locations, automatic failover, and monitoring that alerts you when something breaks. Most established gateways have 99.9% uptime, meaning they are down for fewer than nine hours per year.
Do I need to store transaction history?
Yes. You need to store enough information to reconcile with your processor, handle disputes, and comply with tax and accounting requirements. You should store the transaction ID, the amount, the timestamp, the customer's name and email, the last four digits of the card (not the full number), and the response code. You do not need to store the full card number or CVV.
What is the difference between a payment gateway and a payment processor?
A gateway is the software that handles the transaction on your website. A processor is the company that moves the money. You build the gateway; you contract with the processor. Some companies (like Stripe) provide both, but they are separate functions.
How do I handle chargebacks?
When a customer disputes a charge, their bank sends a chargeback request to your processor. Your processor notifies you and deducts the amount from your account. You can dispute the chargeback by providing evidence that the transaction was legitimate—a signed receipt, shipping confirmation, or email correspondence with the customer. The processor sends your evidence back to the customer's bank, which makes a final decision. This process takes thirty to ninety days.