Name: Hyperswitch PayPal
Availability: InStock
Author: onepush

Deploy and Host self hosted Hyperswitch PayPal (Open-Source Payment Router with PayPal) on Railway

This template gives you a self-hosted Hyperswitch router and its Control Center, so you can add PayPal as a connector with your own Client ID and Secret.

About Hosting Hyperswitch PayPal open-source software on Railway (self hosted Hyperswitch with PayPal template)

Your data stays in your own Railway project. The Hyperswitch router and control center run as containers alongside a Postgres 18 database and a Redis 8.2 instance you control.

The template runs four services: hyperswitch-router on port 8080, control-center on port 9000, Postgres, and Redis.

Why Deploy Hyperswitch PayPal, the PayPal Braintree alternative on Railway (Railway Free Trial)

Self hosting keeps your PayPal credentials, routing rules, and webhook handling under your control instead of inside PayPal Braintree.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Hyperswitch PayPal on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Railway vs Other Hosting Providers and VPS for Hyperswitch PayPal self hosting

Choosing where the Hyperswitch router, control center, Postgres and Redis run shapes how much you own. Here is how Railway compares.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	Four linked services from one template, with Postgres and Redis already wired to the router.	A Droplet you manage, so you install Docker and run the Compose file yourself.
AWS	Generated secrets and public domains without touching VPC or IAM.	Deep networking control, but load balancers, security groups and the database are on you.
Hetzner	Per-service deploys and rollbacks, so you skip patching a box between PayPal sandbox tests.	Low server prices, but you own the OS, backups and firewall rules.

Pick Railway to get PayPal running in test mode fast, and a VPS when you need full host control.

Common Use Cases for hosted Hyperswitch PayPal

PayPal wallet next to cards: Cards and the PayPal wallet sit behind one payment API, and the router picks the connector for each payment. The PayPal wallet row supports automatic and manual capture.
Sandbox testing: Create a PayPal developer app, copy the sandbox Client ID and Client Secret, and run end-to-end tests before switching to live credentials.
Routing PayPal through Adyen or Checkout.com: Customers get redirected to PayPal's site when PayPal runs through another processor. Enable PayPal on that processor's dashboard and in the Control Center.
Refunds and disputes through one API: Webhooks such as PAYMENT.CAPTURE.REFUNDED and CUSTOMER.DISPUTE.CREATED come back through the same path as your card events.
PayPal payouts: Payouts need the payouts feature enabled. Failures usually trace back to missing recipient details like the PayPal email, so fill every required field first.

Dependencies for Hyperswitch PayPal Docker hosted on Railway

Hyperswitch PayPal runs as four services on Railway: the hyperswitch-router, the control-center, Postgres 18, and Redis 8.2. PayPal is not a service you host.

Deployment Dependencies for Managed Hyperswitch PayPal Service (Payment Orchestration)

The router runs ghcr.io/onepush-dev/hyperswitch-router:v1.128.0 on public port 8080, with a health check at /health. Postgres 18 and Redis 8.2 back the router.

Implementation Details for Hyperswitch PayPal (Using Hyperswitch official docker image)

Set ROUTER__USER__BASE_URL to the control-center domain, and point the control center's default__endpoints__api_url at the router domain. Keep the admin API key server side only.

How does Hyperswitch PayPal compare against other ways to accept PayPal

Hyperswitch PayPal trades convenience for control. Here is how it stacks up against the usual routes to PayPal.

Hyperswitch PayPal vs PayPal Braintree (Braintree Alternative)

Ownership: Hyperswitch runs on your own infrastructure, so routing rules and stored data stay with you, while Braintree is PayPal's hosted service.
Key handling: Stored credentials are encrypted with MASTER_ENC_KEY, so back that key up or the data becomes unreadable.
Where Braintree wins: It's a direct PayPal integration with far less to operate if you only need PayPal.

Hyperswitch PayPal vs Stripe PayPal (Stripe Alternative)

Multi-processor routing: Hyperswitch can send PayPal alongside cards through several processors and shift volume between them.
Self-hosting: You run the router and Control Center yourself, so you own the upgrade schedule.
Where Stripe wins: Its checkout tooling is mature, and you avoid running payment infrastructure entirely.

Hyperswitch PayPal vs Adyen (Adyen Alternative)

Open source: Hyperswitch is Apache-2.0 licensed and can be inspected and modified, while Adyen is proprietary.
Connector model: Hyperswitch routes PayPal through its own layer rather than a single acquirer platform.
Where Adyen wins: Its enterprise support and global acquiring coverage are hard to replicate.

Hyperswitch PayPal vs Checkout.com (Checkout.com Alternative)

Unified API: Both give you one API for PayPal and cards, but Hyperswitch keeps the routing logic in your hands.
Hosting: Checkout.com is hosted, whereas Hyperswitch needs Postgres, Redis, router, and dashboard that you maintain.
Where Checkout.com wins: It's a managed processor with less to configure if you don't need custom routing.

How to use Hyperswitch PayPal (the OSS payment orchestrator)?

Here's the first-day path once the stack is up. You'll need a PayPal developer account and your Control Center login.

Create a PayPal developer app at developer.paypal.com and copy the sandbox Client ID and Client Secret.
Log into the Control Center, then add PayPal as a connector with those credentials. Keep sandbox mode on until test payments succeed.
Enable the PayPal wallet payment method and match it to what you turned on in PayPal.
Set the webhook URL in PayPal to your router domain.
Create a test payment through the router API:

curl -X POST https://your-router-domain/payments \
  -H "Content-Type: application/json" \
  -H "api-key: your-merchant-api-key" \
  -d '{"amount": 1000, "currency": "USD", "confirm": true, "payment_method": "wallet", "payment_method_type": "paypal"}'

A PayPal redirect in the response means the connector is wired correctly.

How to self host Hyperswitch PayPal on other VPS Services (Hyperswitch self hosting guide)

Running the stack on your own VPS means you handle the Docker setup, the database, and the Redis instance yourself.

Clone the Repository

git clone https://github.com/juspay/hyperswitch
cd hyperswitch

Install Dependencies

You need Docker and Docker Compose on the host. The repo ships a setup helper at scripts/setup.sh that you can run to check the environment before you start.

Configure Environment Variables

Set the admin API key, JWT secret, and the encryption keys (MASTER_ENC_KEY, HASH_KEY, ENCRYPTION_KEY) in your env file. Point ROUTER__USER__BASE_URL at your-domain for the Control Center.

Start the Hyperswitch PayPal Application

docker compose up -d

Open the Control Center on port 9000, create a merchant, then add PayPal as a connector with your sandbox Client ID and Secret.

Official Pricing of Hyperswitch PayPal (Hyperswitch pricing)

Hyperswitch is open source under Apache-2.0, so self hosting it costs you nothing in licence fees. Check the official pricing page before you budget for it.

Hyperswitch PayPal cloud vs self hosted comparison (Pricing, features, costs, and more)

Self hosting Hyperswitch trades a usage-based hosted plan for infrastructure work you own. Here is what that looks like on Railway and on a VPS, with the PayPal connector in mind.

Monthly cost of self hosting Hyperswitch PayPal on Railway

On Railway, the four services (the router, the control center, Postgres 18, and Redis 8.2) usually run about $15 to $30 per month at light use. Railway's $5 trial helps you get started.

System Requirements for Hosting Hyperswitch PayPal on a VPS

On a VPS, you need a Linux host with Docker and the compose plugin, enough memory for Postgres, Redis, and the Rust router, and a public domain with TLS for the control center and router.

Frequently Asked Questions (FAQs)

Do I use different PayPal credentials for sandbox and live?

Yes. Sandbox testing uses the sandbox Client ID and Secret from your PayPal developer app, and production uses live credentials. Keep them separate so a test payment never reaches a live account.

Which PayPal credentials go into the Control Center?

Enter the Client ID and Client Secret from the PayPal Developer dashboard at developer.paypal.com.

Do I set up PayPal webhooks myself?

Yes, point PayPal's webhook setting at your router's webhook URL. Real webhooks are verified against PayPal's signature endpoint, so an empty test body returning EndpointVerification is expected.

How are refunds and disputes handled?

They flow through the same router API, and the handler recognizes events like PAYMENT.CAPTURE.REFUNDED and CUSTOMER.DISPUTE.CREATED. PayPal still owns buyer protection and dispute resolution.

Can I route PayPal through Braintree or Adyen?

Yes, but the flows differ.

Where are my PayPal credentials stored?

They sit in your self-hosted database, encrypted with MASTER_ENC_KEY. Back that key up, because losing it makes the stored PayPal credentials unreadable.