Stellar TravelPay

Open-source payment infrastructure for hotels, resorts, restaurants, tour operators, and travel businesses. Accept Stellar-based USDC payments and settle globally in seconds.

Overview

TravelPay solves the key pain points hospitality businesses face with traditional payments:

Problem	TravelPay Solution
High card processing fees (2–3%)	Near-zero Stellar network fees
Slow international settlement (1–3 days)	Instant settlement (~5 seconds)
Currency conversion losses	USDC stable value across borders
Expensive remittance	Direct wallet-to-wallet transfers

Tech Stack

Layer	Technology
Frontend	Next.js 14, TypeScript, Tailwind CSS
Backend	NestJS 10, TypeScript, TypeORM
Database	PostgreSQL 16
Blockchain	Stellar SDK v12, Soroban (smart contracts)
Auth	JWT (Bearer token), bcrypt
Monorepo	npm workspaces + Turborepo
Infrastructure	Docker, Railway, GitHub Actions, Terraform

Monorepo Structure

stellar-hospitality/
│
├── apps/
│   ├── merchant-dashboard/     # Next.js merchant portal          :3000
│   ├── customer-wallet/        # Next.js traveler payment page    :3001
│   ├── travelpay-admin/        # Next.js admin panel              :3002
│   └── travelpay-api/          # NestJS REST API                  :4000
│
├── packages/
│   ├── payment-sdk/            # Payment link creation & validation
│   ├── stellar-sdk/            # Stellar SDK wrapper (send, verify, balance)
│   ├── ui-kit/                 # Shared React components
│   └── rewards-contract/       # Soroban loyalty points contract (Rust)
│
├── docs/
│   ├── architecture/           # System overview & ADRs
│   ├── api/                    # Endpoint & webhook reference
│   └── roadmap/                # Product roadmap
│
├── infrastructure/
│   ├── docker/                 # Docker Compose, Dockerfiles, init.sql
│   ├── github-actions/         # CI and deploy workflows
│   └── terraform/              # Railway infrastructure as code
│
└── scripts/
    ├── setup.sh                # Bootstrap local dev environment
    ├── seed.ts                 # Seed demo hotel & payments
    └── generate-keypair.ts     # Generate a Stellar keypair

Getting Started

Prerequisites

Node.js 20+
npm 10+
Docker Desktop (for PostgreSQL)
Git

Quick setup

# 1. Clone
git clone https://github.com/your-org/stellar-hospitality.git
cd stellar-hospitality

# 2. Bootstrap (installs deps, copies .env, starts Postgres, builds packages)
bash scripts/setup.sh

# 3. Fill in your credentials
# Edit .env — minimum required: STELLAR_SECRET_KEY and JWT_SECRET

Manual setup (Windows)

npm install
copy .env.example .env
docker compose -f infrastructure/docker/docker-compose.yml up -d postgres
npm run build --workspace=@travelpay/payment-sdk
npm run build --workspace=@travelpay/stellar-sdk
npm run build --workspace=@travelpay/ui-kit

Seed demo data (optional)

npx ts-node scripts/seed.ts

Generate a Stellar keypair for your merchant account

npx ts-node scripts/generate-keypair.ts

Running the Project

All apps at once (recommended)

npm run dev

Turborepo starts all workspaces in parallel with incremental caching.

Individually

npm run dev --workspace=@travelpay/api               # API        → http://localhost:4000
npm run dev --workspace=@travelpay/merchant-dashboard  # Dashboard  → http://localhost:3000
npm run dev --workspace=@travelpay/customer-wallet     # Wallet     → http://localhost:3001

Other commands

npm run build    # Build all packages and apps
npm run lint     # Lint all workspaces
npm run test     # Run all test suites
npm run format   # Prettier format everything

API Reference

Base URL: http://localhost:4000

Authentication

Method	Endpoint	Description	Auth
`POST`	`/auth/register`	Register a merchant account	Public
`POST`	`/auth/login`	Log in, receive JWT	Public

Payments

Method	Endpoint	Description	Auth
`POST`	`/payments/create`	Create a payment link	Public
`POST`	`/payments/webhook`	Stellar webhook callback	HMAC signature
`GET`	`/payments/status/:id`	Get payment status by ID	Public

Invoices

Method	Endpoint	Description	Auth
`POST`	`/invoices/create`	Create a guest invoice	JWT
`GET`	`/invoices/:hotelId`	List all invoices for a hotel	JWT

Merchant

Method	Endpoint	Description	Auth
`GET`	`/merchant/dashboard`	Dashboard stats for the logged-in merchant	JWT
`GET`	`/merchant/dashboard/:hotelId`	Dashboard stats by hotel ID	JWT

Full request/response examples: docs/api/endpoints.md
Webhook setup & signature verification: docs/api/webhooks.md

Architecture

Traveler Wallet
      │
      ▼
┌────────────────────────┐
│   customer-wallet app  │  Next.js  :3001
│   /pay/:id             │
└──────────┬─────────────┘
           │ REST
           ▼
┌────────────────────────┐
│    TravelPay API       │  NestJS   :4000
└──────────┬─────────────┘
           │
   ┌───────┼────────┐
   ▼       ▼        ▼
 Auth   Invoice  Payment
Module  Service  Service
                   │
                   ▼
┌────────────────────────┐
│      PostgreSQL 16     │  :5432
└────────────────────────┘
                   │
                   ▼
┌────────────────────────┐
│  @travelpay/stellar-sdk│
│  StellarService        │
└──────────┬─────────────┘
           │ Horizon API
           ▼
┌────────────────────────┐
│   Stellar Blockchain   │  testnet / mainnet
└────────────────────────┘

For detailed diagrams and Architecture Decision Records, see docs/architecture/.

Core Features

Merchant Dashboard (`apps/merchant-dashboard`)

Register / login with JWT auth
View payment stats and history
Generate payment links with QR codes
Create and manage guest invoices

Traveler Wallet (`apps/customer-wallet`)

Open a payment link and view amount due
Real-time payment status updates
Step-by-step Stellar wallet instructions

TravelPay API (`apps/travelpay-api`)

Payment creation and webhook handling
HMAC-SHA256 webhook signature verification
JWT-protected merchant routes
TypeORM entities: Hotel, Payment, Invoice

Shared Packages

@travelpay/payment-sdk — createPaymentLink(), validatePayment(), shared types
@travelpay/stellar-sdk — StellarService wrapping sendPayment(), verifyTransaction(), getUsdcBalance()
@travelpay/ui-kit — Button, Badge, Card, QRCode, PaymentStatus components
rewards-contract — Soroban smart contract: award_points, redeem_points, balance

Workflow

1. Merchant registers → receives JWT
2. Merchant calls POST /payments/create with bookingId + amount
3. API returns paymentUrl + QR code
4. Merchant displays QR at checkout or shares link
5. Traveler opens /pay/:id in browser
6. Traveler sends USDC to hotel's Stellar address via their wallet
7. Stellar confirms transaction (~5 seconds)
8. Stellar calls POST /payments/webhook with txHash
9. API updates payment status to "confirmed"
10. Merchant dashboard reflects settlement instantly

Environment Variables

Copy .env.example to .env and fill in:

# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/travelpay

# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_SECRET_KEY=S...
STELLAR_PUBLIC_KEY=G...

# USDC asset
USDC_ASSET_CODE=USDC
USDC_ASSET_ISSUER=GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5

# App
APP_URL=http://localhost:3000
API_URL=http://localhost:4000
JWT_SECRET=change_me_in_production
JWT_EXPIRES_IN=7d

# Webhook signature verification
WEBHOOK_SECRET=change_me_in_production

Testnet funding: Fund your testnet account free via Stellar Friendbot:
curl "https://friendbot.stellar.org?addr=<YOUR_PUBLIC_KEY>"

Future Features

PDF invoice export
Email notifications on payment
Staff tipping flows
Group payment splitting
Reservation deposit holds
Refunds / partial refunds
POS hardware integration
Hotel PMS integration (Opera, Cloudbeds)
Tourism marketplace
Loyalty rewards (Soroban contract — scaffolded in packages/rewards-contract)
Mobile wallet app (React Native)

Full roadmap: docs/roadmap/roadmap.md

Contributing

See CONTRIBUTING.md for setup instructions, branch strategy, commit conventions, and PR guidelines.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
apps		apps
docs		docs
infrastructure		infrastructure
packages		packages
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Stellar TravelPay

Table of Contents

Overview

Tech Stack

Monorepo Structure

Getting Started

Prerequisites

Quick setup

Manual setup (Windows)

Seed demo data (optional)

Generate a Stellar keypair for your merchant account

Running the Project

All apps at once (recommended)

Individually

Other commands

API Reference

Authentication

Payments

Invoices

Merchant

Architecture

Core Features

Merchant Dashboard (apps/merchant-dashboard)

Traveler Wallet (apps/customer-wallet)

TravelPay API (apps/travelpay-api)

Shared Packages

Workflow

Environment Variables

Future Features

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Merchant Dashboard (`apps/merchant-dashboard`)

Traveler Wallet (`apps/customer-wallet`)

TravelPay API (`apps/travelpay-api`)

Packages