Add payment-service microservice for billing and subscriptions

Implements NestJS payment service with Stripe integration, Payment/Invoice/Subscription entities, webhook handling, refund processing, payment method management, Docker config, and unit/e2e tests.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Max-Owolabi

docker-compose.yml

@@ -258,6 +258,33 @@ services:
       - quest-network
     logging: *logging_config
 
+  payment-service:
+    build:
+      context: ./microservices/payment-service
+      dockerfile: Dockerfile
+    container_name: payment_service
+    ports:
+      - "3019:3019"
+    environment:
+      - NODE_ENV=development
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_USER=${DB_USER:-postgres}
+      - DB_PASSWORD=${DB_PASSWORD:-password}
+      - DB_NAME=payment_db
+      - SERVICE_PORT=3019
+      - STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY:-mock}
+      - STRIPE_WEBHOOK_SECRET=${STRIPE_WEBHOOK_SECRET:-whsec_test}
+    volumes:
+      - ./microservices/payment-service:/app
+      - /app/node_modules
+    depends_on:
+      postgres:
+        condition: service_healthy
+    networks:
+      - quest-network
+    logging: *logging_config
+
   moderation-service:
     build:
       context: ./microservices/moderation-service

docker/postgres/init-databases.sh

@@ -22,5 +22,6 @@ create_db "puzzle_db"
 create_db "player_db"
 create_db "moderation_db"
 create_db "analytics_db"
+create_db "payment_db"
 
 echo "All microservice databases created successfully!"

microservices/api-gateway/src/config/configuration.ts

@@ -113,6 +113,11 @@ export default () => ({
             prefix: '/api/replays',
             healthPath: '/health',
         },
+        payment: {
+            url: process.env.PAYMENT_SERVICE_URL || 'http://localhost:3019',
+            prefix: '/api/payments',
+            healthPath: '/health',
+        },
     },
 
     rateLimit: {

microservices/payment-service/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+coverage
+.env
+*.log
+.git

microservices/payment-service/.env.example

@@ -0,0 +1,21 @@
+# Service Configuration
+SERVICE_NAME=payment-service
+SERVICE_PORT=3019
+NODE_ENV=development
+
+# Database Configuration
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=payment_db
+DB_USER=postgres
+DB_PASSWORD=password
+
+# Stripe Configuration
+STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
+STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
+STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key
+
+# PayPal Configuration (optional)
+PAYPAL_CLIENT_ID=your_paypal_client_id
+PAYPAL_CLIENT_SECRET=your_paypal_client_secret
+PAYPAL_MODE=sandbox

microservices/payment-service/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

microservices/payment-service/Dockerfile

@@ -0,0 +1,15 @@
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+
+RUN npm ci --only=production
+
+COPY . .
+
+RUN npm run build
+
+EXPOSE 3019
+
+CMD ["npm", "run", "start:prod"]

microservices/payment-service/README.md

@@ -0,0 +1,52 @@
+# Payment Service
+
+NestJS microservice for fiat payment processing, subscription billing, invoice generation, and refund handling.
+
+## Features
+
+- **Payment Processing** — Process one-time payments via Stripe (with mock fallback for development)
+- **Subscription Billing** — Create, cancel, and bill recurring subscriptions
+- **Invoice Generation** — Generate and manage invoices with line items
+- **Payment Methods** — Store and manage user payment methods
+- **Refund Processing** — Process full or partial refunds
+- **Webhook Handling** — Handle Stripe payment status webhooks securely
+
+## Quick Start
+
+```bash
+cp .env.example .env
+npm install
+npm run start:dev
+```
+
+The service runs on port **3019** by default.
+
+## Docker
+
+```bash
+docker-compose up --build
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| GET | `/payments/providers` | List payment providers |
+| POST | `/payments/:provider/process` | Process a payment |
+| POST | `/payments/:provider/refund` | Refund a payment |
+| POST | `/invoices` | Create an invoice |
+| POST | `/subscriptions` | Create a subscription |
+| POST | `/payment-methods` | Add a payment method |
+| POST | `/webhooks/stripe` | Stripe webhook handler |
+
+## Testing
+
+```bash
+npm test
+npm run test:e2e
+```
+
+## Environment Variables
+
+See `.env.example` for required configuration including Stripe keys and database settings.

microservices/payment-service/docker-compose.yml

@@ -0,0 +1,37 @@
+version: '3.8'
+
+services:
+  payment-service:
+    build: .
+    ports:
+      - '3019:3019'
+    environment:
+      NODE_ENV: development
+      SERVICE_PORT: 3019
+      DB_HOST: postgres
+      DB_PORT: 5432
+      DB_USER: postgres
+      DB_PASSWORD: password
+      DB_NAME: payment_db
+      STRIPE_SECRET_KEY: ${STRIPE_SECRET_KEY:-mock}
+      STRIPE_WEBHOOK_SECRET: ${STRIPE_WEBHOOK_SECRET:-whsec_test}
+    depends_on:
+      - postgres
+    volumes:
+      - .:/app
+      - /app/node_modules
+    command: npm run start:dev
+
+  postgres:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_DB: payment_db
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+    ports:
+      - '5439:5432'
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:

microservices/payment-service/eslint.config.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn',
+      'prettier/prettier': ['error', { endOfLine: 'auto' }],
+    },
+  },
+);