How to build a payment gateway
The parts of a payment gateway, from checkout and tokenisation to routing, disputes and settlement, the card and payment rules behind it, and an order to build it in.
What a payment gateway does
A payment gateway takes payments for merchants: it collects card or bank details securely, sends authorisations to acquirers and networks, handles authentication, refunds and disputes, and reports what will settle and when.
Most teams build on top of licensed acquirers and processors rather than becoming one. The gateway's value is in routing, merchant tools, local payment methods and clear reporting.
The modules you need
Most teams need all of these in the end. The phased plan below sets the order.
Checkout
Hosted fields, payment pages and SDKs that keep card data off the merchant's servers.
Tokenisation vault
Card data swapped for tokens, so stored cards can be charged without holding numbers.
Authentication
3-D Secure and other strong customer authentication flows, with exemption requests.
Routing
Payments sent to the best acquirer or method by country, card type, cost and success rate.
Refunds and captures
Partial and full captures and refunds, with idempotent APIs.
Disputes and chargebacks
Dispute notices, evidence and deadlines in one desk.
Settlement and reporting
What was paid, fees, payouts and reconciliation files for merchants.
Merchant dashboard
Onboarding, transactions, payouts, users and API keys.
How the parts fit together
- 01
Card data in a small zone
Only the vault and its services touch card numbers, keeping PCI DSS scope as small as possible.
- 02
Idempotent payment API
Every request carries a key, so retries never charge twice.
- 03
Processor adapters
One adapter per acquirer, processor or local method.
- 04
Payment state machine
Clear states from created to settled or refunded, with every transition logged.
- 05
Ledger and reconciliation
An internal ledger reconciled against processor settlement files every day.
Data model sketch
- 01
Merchant
Business, KYB status, pricing, payout accounts and users.
- 02
Payment and attempt
The payment and each attempt at each processor, with outcome.
- 03
Token
A reference to stored card or bank details, never the number itself.
- 04
Refund and dispute
Each refund and dispute with reasons, evidence and deadlines.
- 05
Settlement and payout
What the processor settled, fees taken and what was paid out.
Systems it has to talk to
- 01
Acquirers and processors
Card authorisation, capture and settlement.
- 02
Local payment methods
Bank transfers, wallets and QR schemes per country.
- 03
Authentication services
3-D Secure servers and network tokens.
- 04
Fraud tools
Risk scoring before authorisation.
- 05
Merchant systems
Webhooks, plugins and accounting exports.
Rules to design for
Which rules apply depends on your market and product.
- 01
PCI DSS
Applies to every system that stores, processes or sends card data, and to anything connected to them.
- 02
Strong customer authentication
PSD2 in the EU and UK requires SCA on most customer-initiated payments, with set exemptions.
- 03
Licensing
Holding or moving merchants' money can need a payment institution licence or a licensed partner.
- 04
Card network rules
Visa and Mastercard rules on disputes, fees and fraud levels.
- 05
Merchant due diligence
KYB and AML checks on merchants before they take payments.
From prototype to production
Build in this order so something real is in users' hands early.
- 01
Clickable prototype
Checkout and the merchant dashboard, tried by merchants.
- 02
First processor live
Tokenised checkout, authorisation, capture, refunds and the ledger on one acquirer.
- 03
Disputes and settlement
Chargeback desk, settlement reporting and payouts.
- 04
Routing and methods
More acquirers, smart routing and local payment methods.
What drives the cost
These decide most of the budget. For a number based on your own scope, use the cost tool. OceanLab bills $30-50/hr or per milestone.
- 01
PCI DSS scope
The more systems touch card data, the more to secure and assess.
- 02
Processors and methods
Each one is an integration, certification and test plan.
- 03
Markets
Local methods, currencies, tax invoicing and rules per country.
- 04
Disputes
Automating evidence and deadlines across networks.
- 05
Merchant onboarding
KYB checks and risk review for each merchant.
Product builds that match this guide
Cenote - Merchant Dashboard for a Mexican Payment Gateway
Designed and built a clickable merchant dashboard for a Mexican online payment gateway that takes cards with meses sin intereses, SPEI transfers and OXXO cash vouchers in MXN: every payment from authorisation to settlement, declines in plain language, refunds with approval limits, chargebacks sorted by deadline and payouts that break down to the last fee.
Hatid - Remittance App and Ops Console for Sending Money Home to the Philippines
Designed and built a clickable ops console for a Manila remittance company paying out PHP to the families of overseas Filipino workers: a live view of today's flows across 4 corridors, a transfers monitor with SLA timers, a full transfer record, compliance holds with a tipping-off check, and FX margins priced per corridor, payout method and amount band.
Parley - Chargeback Manager with One Dispute Desk Across Every PSP
Designed and built a clickable chargeback manager for a US merchant group with four online brands on Stripe, Adyen and Braintree: one inbox for every dispute with deadline countdowns, evidence gathered per reason code, a fight or accept recommendation with its reasons, pre-dispute alerts and dispute ratios tracked against network thresholds.
Quartet - Buy Now, Pay Later Platform with an Ops Console for Credit, Risk and Hardship
Designed and built a clickable ops console for an Australian buy now, pay later lender that splits online purchases of AUD 50 to AUD 3,000 into 4 or 8 fortnightly instalments: the health of the book, customer records, the fraud and referral queue and hardship cases with their regulatory deadlines.
Rimtang - Phone-as-Till QR and Tap-to-Pay App with an Operations Console
Designed a phone-as-till payments product for a Thai bank-owned payment service provider and its street merchants - dynamic Thai QR, tap to pay on the phone and cash - and built a clickable operations console where staff watch payments, match late QR confirmations by hand and approve the daily settlement run.
Two ways to work with OceanLab
Project build
We design and build the system as one project. It starts with a clickable prototype your team tries before any production code is written. Pay per milestone (outcome-based) or hourly at $30-50/hr, depending on role and seniority.
Embedded engineers
Our engineers join your team on a flexible monthly retainer. Part-time is fine and it runs month to month, with hours that overlap the US, UK and Europe, the Middle East, and Australia and Asia. Outcome-based or $30-50/hr.
Questions
Do we need to become a licensed acquirer?
Usually not. Most gateways work with licensed acquirers and processors. Whether you need your own payment licence depends on whether you hold or move merchants' funds.
How do we keep PCI DSS scope small?
Use hosted fields or a vault so card numbers never touch your main systems, and keep tokens everywhere else.
Why build routing?
Routing across acquirers can raise approval rates and lower costs, and gives a fallback when one processor is down.
