How abhishekdwivedi29/payprox works
1. System shape
- PayProX is a microservice-based payment ecosystem built with Node.js + Express services, MongoDB per service, and React/Vite frontends.
- The core architectural boundary is that each service owns a narrow business domain and exposes REST APIs; cross-service calls happen over HTTP with explicit internal authentication.
2. Client layer
- There are two React frontends:
- frontend: the main customer/merchant-facing product UI with payment, dashboard, refunds, settlements, and auth flows.
- merchant-frontend: a smaller merchant portal focused on merchant pages and orders.
- Both are Vite apps and appear intended for Vercel deployment, while backend services are deployed independently.
3. Merchant domain service
- merchant-service owns merchant authentication and merchant lifecycle actions.
- It exposes auth routes, merchant routes, and public routes for order creation / merchant-facing operations.
- This service is the merchant entry point for initiating orders and triggering settlement-related actions.
4. Customer domain service
- customer-service owns customer registration, login, and customer profile/data management.
- It also exposes internalRoutes for service-to-service validation.
- Customer-facing endpoints are protected by JWT middleware, while internal endpoints use a separate internal auth guard.
5. Payment gateway orchestration service
- payment-gateway-service is the central workflow orchestrator for transactions, sessions, and refunds.
- It contains:
- payment routes and controllers for initiating payments,
- session routes for temporary payment sessions,
- refund routes for request/approval/execution,
- internal routes for service coordination.
- This service is the main transaction hub that coordinates tokenization, risk checks, issuer/acquirer actions, and persistence of Transaction and Refund records.
6. Security and token handling
- Sensitive customer payment flow is protected by verifyCustomerToken in the payment gateway and token-related middleware in the tokenization service.
- tokenization-service replaces raw card data with non-reversible tokens and stores only token metadata in CardToken.
- A shared helper exists at backend/shared/auth/setAuthCookie.js, indicating cookie-based auth setup in addition to JWT handling.
7. Fraud/risk boundary
- risk-engine is a stateless fraud-prevention layer invoked during payment processing.
- It evaluates transaction metadata using rule-based checks such as velocity, thresholds, and blacklist logic.
- Architecturally, it sits between payment initiation and bank authorization, acting as a gate before funds movement proceeds.
8. Banking side: issuer and acquirer
- issuer-service handles customer-side bank account logic and debit/credit operations.
- acquirer-service handles merchant-side bank account logic, merchant crediting/debiting, and balance checks.
- Both services use internal auth middleware, which is important because they are not intended for direct public access; they are invoked by gateway/settlement workflows.
9. Settlement processing
- settlement-engine is responsible for settlement lifecycle management and batch payout logic.
- It has a job entry point (jobs/runSettlement.js) and settlement persistence via the Settlement model.
- The current behavior is merchant-triggered rather than fully scheduled, but it still represents the reconciliation layer that marks eligible transactions as settled and requests merchant credit from the acquirer side.
10. Primary transaction flow
- The diagram should show the flow as:
- merchant creates an order,
- payment gateway creates a short-lived session,
- customer submits payment,
- tokenization verifies card tokens or issuer verifies netbanking credentials,
- risk engine approves/rejects,
- acquirer/issuer execute fund movement,
- payment gateway stores the final transaction state.
- This makes the payment gateway the orchestration spine, with the other services acting as specialized executors.
11. Refund flow
- Refunds are multi-step and cross-service:
- customer initiates refund through the gateway,
- refund is recorded as pending,
- merchant approves/rejects via merchant-facing workflow,
- gateway executes the refund using issuer credit, and if the original transaction was already settled, also triggers acquirer debit from the merchant side.
- This flow crosses payment, merchant, issuer, and acquirer boundaries, with internal auth protecting the service calls.
12. Data ownership and persistence
- Each service has its own src/utils/db.js and local models, indicating database-per-service separation rather than a shared monolith database layer.
- Main persisted entities visible in the tree include:
- Transaction, Refund in payment gateway,
- CardToken in tokenization,
- Settlement in settlement engine,
- Customer, Merchant, and bank-account models in the domain/bank services.
- This separation is key for architecture diagrams: the data model is distributed, not centralized.
13. Service-to-service trust boundary
- Public endpoints are guarded by JWT-based middleware for end-user access.
- Internal endpoints are guarded by internalAuth middleware in most backend services, forming a distinct trust boundary for backend orchestration traffic.
- The architecture therefore has two access layers: external client auth and internal service auth.
14. Deployment and runtime
- Backend services are independently deployable and container-friendly; several services include Dockerfiles and the backend repo includes docker-compose.yml.
- The README indicates deployment on Render for backend services and Vercel for frontends.
- This means the diagram should treat each microservice as separately hosted rather than as a single backend application.
15. What to emphasize in a diagram
- Put payment-gateway-service at the center.
- Connect it to tokenization, risk-engine, issuer-service, acquirer-service, customer-service, merchant-service, and settlement-engine.
- Show the frontends as consumers of merchant/customer/payment APIs.
- Show separate databases per service, plus internal-auth-protected service-to-service links.
Main entry points: src Gateway API · merchant-service Merchant Service · frontend Customer UI · payment-gateway-service Payment Gateway
Components 19
Clients
React/Vite frontends used by customers and merchants.
- Customer UI · Main customer and merchant-facing product frontend for payments, refunds, settlements, and dashboards.
frontend - Merchant Portal · Merchant-focused portal for merchant pages and order flows.
merchant-frontend
Backend
Independently deployable Node.js microservices and their data stores.
- Payment Gateway · Central transaction hub for sessions, payments, refunds, and internal coordination.
backend/services/payment-gateway-service - Gateway API · Public payment, session, and refund endpoints plus internal coordination handlers.
backend/services/payment-gateway-service/src - Gateway DB · Persistent transaction and refund records owned by the payment gateway.
backend/services/payment-gateway-service/src/utils/db.js - Merchant Service · Merchant authentication, merchant lifecycle, and public order initiation entry point.
backend/services/merchant-service - Merchant DB · Merchant identity and lifecycle persistence.
backend/services/merchant-service/src/utils/db.js - Customer Service · Customer registration, login, profile management, and internal validation.
backend/services/customer-service - Customer DB · Customer identity and profile persistence.
backend/services/customer-service/src/utils/db.js - Tokenization · Replaces raw card data with irreversible tokens and stores token metadata.
backend/services/tokenization-service - Token DB · Stored token metadata for payment-card tokenization.
backend/services/tokenization-service/src/utils/db.js - Risk Engine · Stateless rule-based fraud and velocity checks in the payment path.
backend/services/risk-engine - Issuer Service · Customer-side bank account validation and debit/credit execution.
backend/services/issuer-service - Issuer DB · Bank-account persistence for issuer-side operations.
backend/services/issuer-service/src/utils/db.js - Acquirer Service · Merchant-side account checks plus merchant crediting and debiting.
backend/services/acquirer-service - Acquirer DB · Bank-account persistence for acquirer-side operations.
backend/services/acquirer-service/src/utils/db.js - Settlement Engine · Settlement lifecycle and batch payout orchestration, including merchant-triggered reconciliation.
backend/services/settlement-engine - Settlement DB · Settlement persistence for reconciliation and payout processing.
backend/services/settlement-engine/src/utils/db.js
Shared
Cross-cutting helpers used across the backend.
- Auth Cookie · Shared helper for cookie-based auth setup across backend flows.
backend/shared/auth/setAuthCookie.js
Connections 23
- Customer UI → Payment Gateway: customer APIs · Customer UI calls payment, refund, transaction, and settlement APIs.
- Customer UI → Customer Service: auth/profile · Customer UI uses customer auth and profile endpoints.
- Customer UI → Merchant Service: merchant auth · Merchant-facing portions of the product use merchant auth endpoints.
- Merchant Portal → Merchant Service: orders/auth · Merchant portal calls merchant and public order endpoints.
- Merchant Portal → Payment Gateway: order payment · Merchant portal participates in payment and order initiation flows.
- Payment Gateway → Gateway API: exposes · Gateway exposes payment, session, refund, and internal routes.
- Gateway API → Tokenization: tokenize · Gateway delegates card token validation and token-related payment steps.
- Gateway API → Risk Engine: risk check · Gateway invokes fraud/risk evaluation before fund movement.
- Gateway API → Issuer Service: debit/credit · Gateway coordinates issuer-side account movement and refund crediting.
- Gateway API → Acquirer Service: merchant funds · Gateway coordinates merchant-side debits, credits, and balance checks.
- Gateway API → Merchant Service: merchant flow · Gateway coordinates merchant order and refund approval workflows.
- Gateway API → Customer Service: customer flow · Gateway validates customer identity and customer-owned payment actions.
- Gateway API → Settlement Engine: settlement · Gateway triggers settlement-related updates and post-payment reconciliation.
- Merchant Service → Merchant DB: persists · Merchant service owns merchant records and lifecycle state.
- Customer Service → Customer DB: persists · Customer service owns customer records and profiles.
- Tokenization → Token DB: persists · Tokenization service stores card-token metadata only.
- Issuer Service → Issuer DB: persists · Issuer service owns customer bank-account data.
- Acquirer Service → Acquirer DB: persists · Acquirer service owns merchant bank-account data.
- Settlement Engine → Settlement DB: persists · Settlement engine stores reconciliation and settlement state.
- Payment Gateway → Gateway DB: persists · Gateway stores final transaction and refund outcomes.
- Customer UI → Auth Cookie: auth setup · Frontend auth flows align with shared cookie-based auth behavior.
- Merchant Service → Auth Cookie: auth setup · Merchant auth flows use the shared cookie helper pattern.
- Customer Service → Auth Cookie: auth setup · Customer auth flows use the shared cookie helper pattern.