Local Dev Setup

:::info Source Sourced from services/billing-service/LOCAL_DEV_SETUP.md in the documentation repo. :::

1. Prerequisites

Node 20, pnpm 9, Docker 24, Stripe CLI (for webhook forwarding in dev).

2. Quick Start

cd services/billing-service
cp .env.example .env.local
pnpm install
docker compose -f docker-compose.dev.yml up -d
pnpm db:migrate
pnpm seed
pnpm dev                # :3120
pnpm dev:webhook
pnpm dev:worker
stripe listen --forward-to localhost:3120/webhooks/stripe   # Stripe CLI forwards events

3. Dependencies

Service	Port
postgres	5432
redis	6379
nats	4222
stripe-mock	12111
notification-service (mock)	3130
marketplace-service (mock)	3110

4. Environment

PORT=3120
DATABASE_URL=postgres://billing:billing@localhost:5432/billing
REDIS_URL=redis://localhost:6379/120
NATS_URL=nats://localhost:4222
NATS_STREAM=BILLING

STRIPE_MODE=test
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_API_VERSION=2024-09-30.acacia

TAX_PROVIDER=stripe_tax                # or taxjar
TAX_CACHE_TTL_SECONDS=3600

DUNNING_SCHEDULE="1,3,7,10"             # days
PAYOUT_SCHEDULE="0 0 * * 5"              # weekly Friday
PAYOUT_MIN_BALANCE_MICRO=5000000         # $50
RECONCILIATION_SCHEDULE="0 2 * * *"      # daily 2 AM

PLATFORM_REVENUE_SHARE_BPS=1500

5. Seed Data

• 3 customers (tenants).
• 2 active subscriptions (trialing + active).
• 5 invoices (paid, open, overdue).
• Several payments (successful, failed, refunded).
• 1 in-progress dunning.
• 2 completed payouts.

6. Commands

pnpm dev
pnpm test
pnpm test:integration
pnpm test:stripe:scenarios     # stripe-mock scenarios
pnpm reconcile:run
pnpm dunning:advance           # manual advance for testing
pnpm payout:trigger
pnpm pci:scan                  # verify no PAN in logs

7. Debugging

• Stripe CLI logs all forwarded events.
• pnpm stripe:sim --amount 4999 --decline simulates decline.
• pnpm reconcile:inspect shows variance report.