SolveEase Pay — Architecture Documentation

Platform: pay.solveease.in
Version: 1.0
Updated: 2026-08-02

Overview

SolveEase Pay is a centralised multi-tenant payment gateway built on top of Cashfree PG. It allows any SolveEase product (e.g. mridu-ai.com) to initiate, manage, and receive payment confirmations through a single unified API and hosted checkout UI.

High-Level Architecture

┌──────────────────────────────────────────────────────────────────┐
│                    Product Integrations                          │
│   mridu-ai.com │ product-b.com │ product-c.com │ ...            │
└────────────────────────┬─────────────────────────────────────────┘
                         │  POST /api/v1/orders  (API Key Auth)
                         ▼
┌──────────────────────────────────────────────────────────────────┐
│                  pay.solveease.in (Next.js 15)                   │
│                                                                  │
│  ┌─────────────┐   ┌──────────────┐   ┌─────────────────────┐   │
│  │ API Routes  │   │ Checkout UI  │   │  Admin Dashboard    │   │
│  │ /api/v1/    │   │ /pay/[id]    │   │  /admin/*           │   │
│  └──────┬──────┘   └──────┬───────┘   └─────────────────────┘   │
│         │                 │                                      │
│  ┌──────▼─────────────────▼──────┐                              │
│  │      Service Layer             │                              │
│  │  CashfreeService │ OrderService│                              │
│  │  TenantService   │ AuthService │                              │
│  └──────────────────┬────────────┘                              │
│                     │                                            │
│  ┌──────────────────▼────────────┐                              │
│  │   Prisma ORM → PostgreSQL     │                              │
│  └───────────────────────────────┘                              │
└───────────────────────────────────┬──────────────────────────────┘
                                    │
                         ┌──────────▼──────────┐
                         │   Cashfree PG API   │
                         │  (Order, Webhook)   │
                         └──────────┬──────────┘
                                    │  Webhook
                         ┌──────────▼──────────┐
                         │  /api/webhooks/     │
                         │  cashfree (HMAC     │
                         │  verified handler)  │
                         └──────────┬──────────┘
                                    │  Tenant Webhook
                         ┌──────────▼──────────┐
                         │  Product Backend    │
                         │  (mridu-ai.com etc) │
                         └─────────────────────┘

Directory Structure

payment_gt/
├── src/
│   ├── app/
│   │   ├── (public)/
│   │   │   ├── page.tsx               # Landing page
│   │   │   ├── pay/
│   │   │   │   └── [orderId]/
│   │   │   │       └── page.tsx       # Hosted checkout
│   │   │   ├── success/
│   │   │   │   └── page.tsx           # Payment success
│   │   │   └── failed/
│   │   │       └── page.tsx           # Payment failed
│   │   ├── (admin)/
│   │   │   ├── admin/
│   │   │   │   ├── page.tsx           # Admin login
│   │   │   │   ├── dashboard/
│   │   │   │   ├── tenants/
│   │   │   │   └── transactions/
│   │   └── api/
│   │       ├── v1/
│   │       │   ├── orders/
│   │       │   │   ├── route.ts       # POST create order
│   │       │   │   └── [id]/
│   │       │   │       └── route.ts   # GET order status
│   │       ├── webhooks/
│   │       │   └── cashfree/
│   │       │       └── route.ts       # Cashfree webhook
│   │       └── internal/
│   │           ├── auth/route.ts      # Admin login
│   │           └── tenants/route.ts   # Tenant CRUD
│   ├── lib/
│   │   ├── cashfree/
│   │   │   └── index.ts               # Cashfree SDK wrapper
│   │   ├── db/
│   │   │   └── index.ts               # Prisma singleton
│   │   ├── auth/
│   │   │   ├── api-key.ts             # API key helpers
│   │   │   └── jwt.ts                 # Admin JWT helpers
│   │   ├── validation/
│   │   │   └── schemas.ts             # Zod schemas
│   │   └── security/
│   │       ├── webhook.ts             # HMAC verification
│   │       └── rate-limit.ts          # Rate limiter
│   ├── components/
│   │   ├── checkout/
│   │   ├── admin/
│   │   └── ui/
│   ├── hooks/
│   ├── types/
│   │   └── index.ts
│   └── middleware.ts
├── prisma/
│   └── schema.prisma
├── docs/
│   ├── ARCHITECTURE.md
│   ├── INTEGRATION_GUIDE.md
│   ├── API_REFERENCE.md
│   ├── SECURITY.md
│   ├── DEPLOYMENT.md
│   └── TESTING.md
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
└── .env.example

Data Flow: Payment Creation

1. Product sends POST /api/v1/orders with API key + payload
2. Middleware validates API key → resolves Tenant record
3. OrderService creates Order in DB (status: PENDING)
4. CashfreeService calls Cashfree PGCreateOrder
5. Cashfree returns cashfree_order_id + payment_session_id
6. Order updated in DB with session ID (status: ACTIVE)
7. Gateway returns { orderId, paymentUrl }
8. Product redirects customer to paymentUrl
9. Customer lands on /pay/[orderId], Cashfree JS SDK loads checkout
10. Customer completes payment
11. Cashfree fires webhook to /api/webhooks/cashfree
12. Webhook handler: verify HMAC → update Order (status: PAID/FAILED)
13. Tenant webhook URL is notified (signed payload)
14. Customer is redirected to /success or /failed
15. /success redirects to product returnUrl

Multi-Tenancy Model

Each product is a Tenant record in the database:

All orders belong to a tenant. The checkout page shows the tenant's branding.

Security Architecture

See SECURITY.md for full details.

Key principles:

• Zero trust on the frontend — amount is never accepted from the browser
• API keys are hashed — raw key sent once at creation, never stored
• Webhook authenticity — all Cashfree webhooks are HMAC-verified
• Tenant isolation — one tenant cannot access another's orders