Deploy Hyperswitch Braintree

Deploy and Host self hosted Hyperswitch Braintree (Payment Gateway Connector Setup) on Railway

This template deploys a self-hosted Hyperswitch stack on Railway, with the router, control center, Postgres and Redis already wired together.

About Hosting Hyperswitch Braintree open-source software on Railway (self hosted Braintree connector for the Hyperswitch payment orchestrator template)

This template runs the Hyperswitch router, the control center, Postgres 18 and Redis 8.2 in your own Railway project.

Braintree is connected in the control center by pasting your Public Key and Private Key. Keep those keys server side.

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

Want to skip Stripe's hosted stack?

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 Braintree 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 Braintree self hosting

Railway runs the router, control center, Postgres and Redis for you, so you skip the server work.

Pick Railway for a fast connector setup, and a VPS when you need full host control.

Common Use Cases for hosted Hyperswitch Braintree

• Routing card and wallet payments behind one endpoint: Your backend sends every charge to POST /payments with your api-key header, and Hyperswitch handles the Braintree call for cards, Apple Pay, Google Pay and PayPal.
• Testing in the Braintree sandbox first: Register at braintreepayments.com/sandbox, add the sandbox keys to the connector, and run your full checkout before real money moves.
• Receiving webhooks into your backend: Register the webhook endpoint from the Hyperswitch Control Center under Home, Settings, API, Webhooks in Braintree, so payment and refund events reach your server.
• Tracking dispute_opened and dispute_lost: Watch dispute_opened to start gathering evidence early, and use dispute_lost to stop fulfilling the order.
• Comparing Braintree against other connectors: Each processor is a connector in the same control center, so you can split traffic and compare results without rebuilding your integration.

Dependencies for Hyperswitch Braintree Docker hosted on Railway

This stack has four services: the hyperswitch-router, the control-center dashboard, Postgres 18 and Redis 8.2.

Deployment Dependencies for Managed Hyperswitch Braintree Service (Payment Orchestration)

The template wires the services together on Railway.

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

If you run the official image yourself, pull ghcr.io/onepush-dev/hyperswitch-router:v1.128.0 and expose port 8080 for the router and port 9000 for the control center.

How does Hyperswitch Braintree compare against other ways to connect Braintree to a self-hosted payment router

Braintree is a PayPal service, so the real question is whether you want a router in front of it.

Hyperswitch Braintree vs Braintree direct (PayPal Braintree Gateway Alternative)

• Routing Control: Braintree direct sends every payment to Braintree. Hyperswitch keeps Braintree as one connector among several, so you can split or fail over traffic.
• Setup Effort: Braintree direct needs only your keys and the official SDK. Hyperswitch adds a router and dashboard you must host.
• Where Direct Wins: If Braintree is your only processor, the direct integration has fewer moving parts.

Hyperswitch Braintree vs Stripe (Stripe Alternative for Self-Hosted Routing)

• Ownership: Stripe is a proprietary processor you rent. Hyperswitch is Apache-2.0 open source that you run yourself.
• Operations: Stripe handles uptime and compliance tooling. With Hyperswitch you own the router, Postgres and Redis.
• Where Stripe Wins: If you want one vendor with no infrastructure to run, Stripe is the easier path.

Hyperswitch Braintree vs Adyen (Adyen Enterprise Acquirer Alternative)

• Acquiring: Adyen is an enterprise acquirer. Hyperswitch routes to processors like Braintree, so acceptance economics still come from Braintree.
• Cost Model: Hyperswitch is free to self host, with Railway at roughly $15-30 per month for light use. Adyen pricing is negotiated.
• Where Adyen Wins: For large merchants needing global acquiring and direct enterprise support, Adyen is stronger.

Hyperswitch Braintree vs Checkout.com (Checkout.com Payment Processor Alternative)

• Architecture: Checkout.com offers one commercial API across acquiring and payment methods. Hyperswitch lets you choose connectors and swap Braintree out later.
• Hosting Burden: Checkout.com runs its own infrastructure. With Hyperswitch you deploy the router and dashboard, back up MASTER_ENC_KEY, and watch /health/ready.
• Where Checkout.com Wins: If you want a supported processor with minimal engineering time, it removes the router layer entirely.

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

Finish everything in sandbox before real money touches the router.

1. Register a Braintree sandbox account at braintreepayments.com/sandbox.
2. Open your control center domain and sign in.
3. In Braintree, go to Home to Settings to API and copy the Public Key and Private Key.
4. Add Braintree as a connector and paste both keys into the connector configuration.
5. Leave the shared third credential field empty.
6. Follow "Activate a connector on Hyperswitch": PSP registration, platform access, credential mapping, method configuration, activation.
7. Copy the webhook endpoint URL from the control center and register it under Home to Settings to API to Webhooks in Braintree.
8. Send a test payment to your router domain with your api-key header:

curl -X POST https://your-router-domain/payments \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"amount": 1000, "currency": "USD", "confirm": true, "payment_method": "card", "payment_method_data": {"card": {"card_number": "4111111111111111", "card_exp_month": "12", "card_exp_year": "2030", "card_holder_name": "Test User", "card_cvc": "123"}}}'

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

You can run the same Hyperswitch stack on any Linux VPS with Docker, using the Apache-2.0 project at github.com/juspay/hyperswitch.

Clone the Repository

Clone the repo and move into it.

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

Install Dependencies

You need Docker with the Compose plugin and enough memory for Postgres, Redis, the router and the control center.

docker --version
docker compose version

Configure Environment Variables

Generate your secrets and back up the encryption keys, because losing MASTER_ENC_KEY makes stored data unreadable.

export ROUTER__SECRETS__ADMIN_API_KEY="$(openssl rand -hex 16)"
export MASTER_ENC_KEY="$(openssl rand -hex 32)"
export ROUTER__USER__BASE_URL="https://your-domain:9000"
export default__endpoints__api_url="https://your-domain:8080"

Start the Hyperswitch Braintree Application

Start the stack and check the router health endpoint.

docker compose up -d
curl http://your-domain:8080/health

Railway handles the Postgres, Redis, networking and domains for you.

Official Pricing of Hyperswitch Braintree (Hyperswitch pricing)

Hyperswitch is open source under the Apache-2.0 license, so the router and control center cost nothing in license fees.

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

Self hosting Hyperswitch means you pay for the stack and the processor fees, not a platform subscription.

Monthly cost of self hosting Hyperswitch Braintree on Railway

The four services are hyperswitch-router, control-center, Postgres 18 and Redis 8.2. Braintree's processing fees are billed separately.

System Requirements for Hosting Hyperswitch Braintree on a VPS

Running the router, dashboard, Postgres and Redis on a VPS is heavier than a single small app.

Frequently Asked Questions (FAQs)

Where do I find the Braintree Public Key and Private Key?

In the Braintree dashboard, go to Home / Settings / API and copy both keys.

Is there a Merchant ID field I need to fill?

The upstream Braintree connector page doesn't document a Merchant ID field.

How do I switch between sandbox and production?

The upstream docs don't describe a sandbox or production switch for this connector.

Which payment methods and card networks does the connector support?

Cards, Apple Pay, Google Pay and PayPal are supported.

How are Braintree webhook signatures verified?

Signatures are checked with HMAC-SHA1 over the signature and encoded payload in the form body.

Which dispute events are recognized?

The connector recognizes dispute_opened, dispute_lost, dispute_won, dispute_accepted, dispute_auto_accepted, dispute_expired and dispute_disputed.