What “self-hosted payment gateway” actually means, and what you take ownership of.
Self-hosting does not make you a card acquirer. It means running the layer that sits between your checkout and your PSP accounts: routing, payment state, webhooks, billing workflows, and the dashboard your team operates with. This guide lays out what that layer contains and how to judge whether you should run it.
Search intent
Understand what self-hosting a payment gateway layer means and whether the operational trade-off is worth it.
User job
Decide between building on a hosted PSP dashboard, buying a SaaS orchestration layer, or running an open-source payment platform on owned infrastructure.
Useful artifact
Self-hosting readiness checklist and an operational-signal response table.
You self-host the operations layer. The PSPs still move the money.
A self-hosted payment gateway layer is software you deploy that accepts payment intents, routes them to PSP accounts you own (Stripe, Square, Braintree, Mollie, and others), and keeps durable financial state in your database.
Money still settles through the PSPs. Self-hosting changes who controls routing, data, retention, and operations — not who acquires the card transaction.
The minimum viable footprint is small: a backend, a Postgres instance, and provider credentials. Production adds monitoring, backups, webhook delivery, and upgrade discipline.
Sensitive card data should stay with the PSPs or their hosted fields/SDKs. A well-designed self-hosted layer stores provider token references, never raw card numbers.
Choose self-hosting when data control, provider flexibility, or flat cost matters more than having a vendor on call. Choose hosted when the team cannot own another production system.
The five steps from clone to first routed charge.
01
Deploy the stack
Run the platform with Docker Compose or your orchestrator of choice: backend, Postgres as financial source of truth, and the operations dashboard.
02
Start with a simulator
Exercise checkout, declines, refunds, and webhooks against a deterministic simulated provider before any real PSP credential exists in the system.
03
Connect provider accounts
Add credentials for the PSP accounts you already own. Keep TEST and LIVE modes isolated end to end — separate keys, separate data scopes.
04
Publish route policies
Make routing explicit: which provider account handles which country, currency, and method, and what counts as a fallback-eligible failure.
05
Wire operations
Point webhooks at your systems, set up dashboards and alerts, and rehearse the runbook for provider outages and failed deliveries.
Use this checklist before committing to self-hosting.
Self-hosting trades a vendor bill for operational ownership. It works when the team can answer for deployment, upgrades, monitoring, and incident response — and it fails quietly when nobody owns those.
Someone owns the deployment
Upgrades, migrations, backups, and restarts need a named owner, not a hope that the platform never changes.
Postgres is treated as financial truth
Backups are tested, storage is monitored, and no cache or queue is allowed to become the authority for charge state.
Card data never touches your servers
Tokenization stays with PSP hosted fields or SDKs. Your layer stores provider token references and safe metadata only.
Webhook delivery is observable
Signed payloads, delivery logs, and replay let you answer “did the merchant system hear about this payment?” months later.
TEST and LIVE are separated everywhere
Keys, data, dashboards, and alerts must be mode-scoped so a test misconfiguration can never leak into live money flows.
You have an exit and upgrade story
Open-source licensing, plain Postgres tables, and documented schemas mean you can leave, fork, or upgrade on your own schedule.
Operational signals and how a self-hosted deployment should respond.
| Signal | Route action | Stop condition |
|---|---|---|
| A PSP starts timing out | Route policy shifts eligible traffic to a backup provider account you own. | Stop when the backup cannot support the payment context or fallback budget is exhausted. |
| Webhook consumer goes down | Deliveries queue with retries; replay them from the dashboard once the consumer recovers. | Investigate payloads that still fail after replay instead of retrying forever. |
| Database storage pressure | Alert early, grow the volume, and archive projections — never prune authoritative payment tables casually. | Stop accepting new charges before risking writes to financial state. |
| A platform upgrade lands | Apply migrations in a staging copy first, then upgrade with a tested rollback path. | Do not run mixed schema versions against one financial database. |
Where this fits in a payment orchestration system.
MasonXPay uses routing, provider adapters, durable payment state, and operations tooling to keep the payment path inspectable. It is not a card network, acquirer, or replacement for PSP acquiring.
Single-command local start
MasonXPay runs with Docker Compose: backend, Postgres, dashboard, and the Mason Simulator for provider-free testing.
Durable financial state
Payments, attempts, refunds, and invoices live in Postgres tables designed as the source of truth, with idempotency checks on funds-moving actions.
Provider adapters you configure
Implemented adapters for Stripe, Square, Braintree, and Mollie connect to accounts you own; credentials are encrypted at rest.
Operations dashboard included
Payment search, webhook delivery inspection and replay, route policy management, and billing workflows ship with the platform.
MIT-licensed exit story
Self-host for free under MIT, or use the managed plan at $99/month flat — the schema and data remain yours either way.
Self-hosted payment gateway questions
Does self-hosting a payment gateway make me a payment processor?
No. Acquiring, settlement, and card-network access stay with the PSPs. You host the routing, state, and operations layer on top of provider accounts you own.
Do I need PCI DSS Level 1 to self-host this layer?
If card data is tokenized by PSP hosted fields or SDKs and your servers never see PANs, your scope stays dramatically smaller. Verify scope with your assessor; never design a flow where raw card data reaches your backend.
What is the smallest team that can run this responsibly?
One engineer who already operates production services can run the stack; the honest requirement is ownership of backups, upgrades, and alerts rather than headcount.
What does self-hosting cost compared to SaaS orchestration?
Infrastructure for a small deployment is typically a few small VMs plus Postgres. The real cost is operational time — which is why a flat managed option exists for teams that want the platform without the pager.
Build payment routing you can explain.
Explore the provider catalog, inspect the open-source implementation, or compare route policy design against your current payment stack.