Conductor - a smart payment switch

Conductor is an open-source payment switch that simplifies handling multiple payment providers. It supports Stripe, Xendit, Airwallex and Razorpay, giving you a unified interface for payments, subscriptions, and dispute management. Perfect for when you need more than one payment provider to handle different currencies or regions.

The system includes an experimental fraud detection with AI that analyzes transactions in real-time before processing payments. It uses OpenAI's LLM models to identify suspicious patterns while maintaining strict privacy standards by anonymizing sensitive data. The fraud detection layer integrates easily into your payment flow, automatically trying to block high-risk transactions while allowing legitimate ones to proceed smoothly.

Tip

Architecture: docs/ARCHITECTURE.md | API Reference: docs/api.html (OpenAPI)

Setup

1. Get the dependencies

go mod download

2. Set up your database

# Connect to PostgreSQL
psql -U postgres

# Create database and user
CREATE DATABASE conductor;
CREATE USER conductor_user WITH PASSWORD 'your_password_here';
GRANT ALL PRIVILEGES ON DATABASE conductor TO conductor_user;

# Exit psql
\q

# Run the schema migration
psql -U conductor_user -d conductor -f config/db/schema.sql

Tip

Want to automate the database setup? See the Development Guide for a handy script.

3. Configure the app

Option 1: Using Environment Variables (Recommended for Production)

# Copy the environment template
cp env.example .env

# Edit .env with your actual values:
# - Set secure database credentials
# - Add your Stripe API keys
# - Add your Xendit API keys
# - Add your Razorpay API keys
# - Add your OpenAI API key for fraud detection (experimentation and optional)
# - Adjust server settings if needed

# Load environment variables
export $(cat .env | xargs)

Option 2: Using Configuration File (Development Only)

# Copy the example config
cp config/config.example.json config/config.json

# Edit config.json with your settings:
# - Update database credentials
# - Add your Stripe API keys
# - Add your Xendit API keys
# - Add your Razorpay API keys
# - Add your OpenAI API key for fraud detection (experimental and optional)
# - Adjust server settings if needed

⚠️ Security Note: For production deployments, it is advised to use environment variables for API keys and database passwords.

Running the App

Start the server:

go run main.go

Your API will be live at http://localhost:8080

API Documentation

Interactive API docs (Swagger UI):

make api-docs

Opens at http://localhost:8090/api.html. OpenAPI spec available at docs/openapi.yaml.

Docker setup

Environment Variables (optional)

Create a .env file in the project root:

XENDIT_API_KEY=your_xendit_api_key
STRIPE_API_KEY=your_stripe_api_key

Running with Docker

Build and start everything:

docker-compose up --build

Development with Docker

• Rebuild the image: docker-compose build
• Run tests in Docker: docker-compose run --rm conductor go test ./...

Accessing the App

The app will be available at http://localhost:8080

Authentication

All API endpoints (except health check) require authentication using an API key. You can provide the API key in two ways:

1. X-API-Key header (recommended):

   curl -H "X-API-Key: your_api_key_here" http://localhost:8080/v1/charges

2. Authorization Bearer header:

   curl -H "Authorization: Bearer your_api_key_here" http://localhost:8080/v1/charges

Note: Replace your_api_key_here with your actual API key. For development, you can use any string with at least 10 characters.

How Routing Works

The system routes payments using a weighted scoring engine:

Provider	Currencies	Best For
Stripe	USD, EUR, GBP, CAD	International payments
Xendit	IDR, SGD, MYR, PHP, THB, VND	Southeast Asia
Razorpay	INR	India (UPI, Netbanking)
Airwallex	HKD, CNY, AUD, NZD, JPY, KRW	APAC cross-border

Routing Features:

• Circuit Breakers - Auto-failover when providers degrade
• BIN/IIN Routing - Route cards to historically best-performing provider
• Smart Retry - Automatic retry with exponential backoff and provider failover
• Real-time Scoring - Weighted by success rate, cost, latency, and health
• Merchant Config - Per-merchant provider preferences and volume targets

Tip

For more details on smart routing, see the Smart Routing Guide.

Documentation

Document	Description
API Reference	Interactive OpenAPI docs (make api-docs)
Architecture	System design (make diagram for interactive)
Smart Routing	Routing engine details
Fraud Detection	AI-powered fraud prevention
Security Guide	Security checklist
Development Guide	Database setup, caching