# erumpay/payment-service architecture

> Architecture diagram of the GitHub repository erumpay/payment-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erumpay/payment-service
- Repository: https://github.com/erumpay/payment-service

## Overview

This is a Spring payment-service covering standard and merchant payments, QR checkout, Dutch split payments, and remote-payment requests. Its domain services coordinate payment state, persistence, and external authorization, card, payment-gateway, merchant, and recommendation clients; Dutch and remote flows also provide live status updates. The README gives no workflow detail, and controllers and several subsystems were not sampled, so their entry-point wiring is not asserted. Edges below are limited to relationships visible in sampled excerpts or the source index.

Main entry points: [`src/main/java/com/erumpay/payment/core/service/CoreService.java`](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/service/CoreService.java) (Payment Orchestration), [`src/main/java/com/erumpay/payment/core/dao/CoreRepository.java`](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/dao/CoreRepository.java) (Payment Records), [`src/main/java/com/erumpay/payment/remote/service/RemotePayService.java`](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/service/RemotePayService.java) (Remote Payments), [`src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java`](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java) (Merchant Payments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Payments"]
  node_core_api["Core API"]
  node_core_service["Payment Orchestration<br/>[CoreService.java]"]
  node_core_persist["Payment Persistence"]
  node_core_validation["Payment Validation"]
  node_payment_store[("Payment Records")]
  node_card_store[("Card Records")]
  node_payment_state["Payment State<br/>[CoreEntity.java]"]
end

subgraph group_integrations["Payment Integrations"]
  node_auth_client["Auth Client<br/>[AuthClient.java]"]
  node_card_client["Card Client<br/>[CardClient.java]"]
  node_pg_client["Gateway Client<br/>[PgClient.java]"]
  node_recommend_client["Recommendation Client"]
end

subgraph group_merchant_qr["Merchant and QR"]
  node_merchant_api["Merchant Payments"]
  node_merchant_controller["Merchant API"]
  node_merchant_client["Merchant Lookup"]
  node_qr_service["QR Checkout<br/>[QrService.java]"]
  node_qr_store[("QR Records<br/>[QrRepository.java]")]
end

subgraph group_shared_pay["Split and Remote"]
  node_dutch_service["Dutch Payments"]
  node_dutch_store[("Dutch Sessions")]
  node_participant_store[("Participants")]
  node_remote_service["Remote Payments"]
  node_remote_store[("Remote Requests")]
  node_remote_validator["Friend Validator"]
end

subgraph group_realtime["Live Updates"]
  node_dutch_sse["Dutch Live Updates"]
  node_remote_sse["Remote Live Updates"]
  node_notifications["Payment Notifications"]
end

node_user(("User"))
node_merchant(("Merchant Client"))
node_gateway(("Payment Gateway"))

node_core_service -->|"calls"| node_auth_client
node_core_service -->|"calls"| node_card_client
node_core_service -->|"calls"| node_pg_client
node_core_service -->|"calls"| node_recommend_client
node_core_service -->|"reads/writes"| node_payment_store
node_core_service -->|"reads/writes"| node_card_store
node_core_service -->|"delegates to"| node_core_persist
node_core_persist -->|"reads/writes"| node_payment_store
node_merchant_api -->|"reads/writes"| node_payment_store
node_merchant_api -->|"reads"| node_card_store
node_merchant_api -->|"calls"| node_pg_client
node_merchant_api -->|"calls"| node_merchant_client
node_qr_service -->|"reads/writes"| node_payment_store
node_qr_service -->|"reads/writes"| node_qr_store
node_qr_service -->|"delegates to"| node_core_persist
node_qr_service -->|"calls"| node_merchant_client
node_dutch_service -->|"reads/writes"| node_payment_store
node_dutch_service -->|"reads/writes"| node_dutch_store
node_dutch_service -->|"reads/writes"| node_participant_store
node_dutch_service -->|"publishes updates"| node_dutch_sse
node_remote_service -->|"reads"| node_payment_store
node_remote_service -->|"reads/writes"| node_remote_store
node_remote_service -->|"calls"| node_remote_validator
node_remote_service -->|"publishes updates"| node_remote_sse
node_remote_service -->|"publishes events"| node_notifications
node_dutch_sse -->|"reads"| node_dutch_store
node_dutch_sse -->|"reads"| node_participant_store
node_gateway -.->|"payment calls"| node_pg_client
node_user -.->|"requests"| node_core_api
node_user -.->|"requests"| node_merchant_controller

click node_core_api "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/controller/CoreController.java"
click node_core_service "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/service/CoreService.java"
click node_core_persist "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/service/CorePgPaymentPersistenceService.java"
click node_core_validation "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/service/CoreValidationService.java"
click node_payment_store "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/dao/CoreRepository.java"
click node_card_store "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/dao/CardDetailRepository.java"
click node_payment_state "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/domain/entity/CoreEntity.java"
click node_auth_client "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/auth/AuthClient.java"
click node_card_client "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/card/CardClient.java"
click node_pg_client "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/pg/PgClient.java"
click node_recommend_client "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/recommend/RecommendClient.java"
click node_merchant_api "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java"
click node_merchant_controller "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/merchant/controller/MerchantPaymentController.java"
click node_merchant_client "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/merchant/client/MerchantClient.java"
click node_qr_service "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/qr/service/QrService.java"
click node_qr_store "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/qr/dao/QrRepository.java"
click node_dutch_service "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/service/DutchPayService.java"
click node_dutch_store "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/dao/DutchPaySessionRepository.java"
click node_participant_store "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/dao/DutchPayParticipantRepository.java"
click node_remote_service "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/service/RemotePayService.java"
click node_remote_store "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/dao/RemotePayRequestRepository.java"
click node_remote_validator "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/service/RemotePayFriendValidator.java"
click node_dutch_sse "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/service/DutchPaySseService.java"
click node_remote_sse "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/service/RemotePaySseService.java"
click node_notifications "https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/notification/service/PaymentNotificationEventPublisher.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_api,node_core_service,node_core_persist,node_core_validation,node_payment_store,node_card_store,node_payment_state,node_user,node_merchant toneBlue
class node_auth_client,node_card_client,node_pg_client,node_recommend_client toneAmber
class node_merchant_api,node_merchant_controller,node_merchant_client,node_qr_service,node_qr_store toneMint
class node_dutch_service,node_dutch_store,node_participant_store,node_remote_service,node_remote_store,node_remote_validator toneRose
class node_dutch_sse,node_remote_sse,node_notifications,node_gateway toneIndigo
```

## Components

### Core Payments

- [Core API](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/controller/CoreController.java): `src/main/java/com/erumpay/payment/core/controller/CoreController.java`
- [Payment Orchestration](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/service/CoreService.java): `src/main/java/com/erumpay/payment/core/service/CoreService.java`
- [Payment Persistence](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/service/CorePgPaymentPersistenceService.java): `src/main/java/com/erumpay/payment/core/service/CorePgPaymentPersistenceService.java`
- [Payment Validation](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/service/CoreValidationService.java): `src/main/java/com/erumpay/payment/core/service/CoreValidationService.java`
- [Payment Records](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/dao/CoreRepository.java): `src/main/java/com/erumpay/payment/core/dao/CoreRepository.java`
- [Card Records](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/dao/CardDetailRepository.java): `src/main/java/com/erumpay/payment/core/dao/CardDetailRepository.java`
- [Payment State](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/domain/entity/CoreEntity.java): `src/main/java/com/erumpay/payment/core/domain/entity/CoreEntity.java`

### Payment Integrations

- [Auth Client](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/auth/AuthClient.java): `src/main/java/com/erumpay/payment/core/client/auth/AuthClient.java`
- [Card Client](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/card/CardClient.java): `src/main/java/com/erumpay/payment/core/client/card/CardClient.java`
- [Gateway Client](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/pg/PgClient.java): `src/main/java/com/erumpay/payment/core/client/pg/PgClient.java`
- [Recommendation Client](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/core/client/recommend/RecommendClient.java): `src/main/java/com/erumpay/payment/core/client/recommend/RecommendClient.java`

### Merchant and QR

- [Merchant Payments](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java): `src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java`
- [Merchant API](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/merchant/controller/MerchantPaymentController.java): `src/main/java/com/erumpay/payment/merchant/controller/MerchantPaymentController.java`
- [Merchant Lookup](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/merchant/client/MerchantClient.java): `src/main/java/com/erumpay/payment/merchant/client/MerchantClient.java`
- [QR Checkout](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/qr/service/QrService.java): `src/main/java/com/erumpay/payment/qr/service/QrService.java`
- [QR Records](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/qr/dao/QrRepository.java): `src/main/java/com/erumpay/payment/qr/dao/QrRepository.java`

### Split and Remote

- [Dutch Payments](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/service/DutchPayService.java): `src/main/java/com/erumpay/payment/dutch/service/DutchPayService.java`
- [Dutch Sessions](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/dao/DutchPaySessionRepository.java): `src/main/java/com/erumpay/payment/dutch/dao/DutchPaySessionRepository.java`
- [Participants](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/dao/DutchPayParticipantRepository.java): `src/main/java/com/erumpay/payment/dutch/dao/DutchPayParticipantRepository.java`
- [Remote Payments](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/service/RemotePayService.java): `src/main/java/com/erumpay/payment/remote/service/RemotePayService.java`
- [Remote Requests](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/dao/RemotePayRequestRepository.java): `src/main/java/com/erumpay/payment/remote/dao/RemotePayRequestRepository.java`
- [Friend Validator](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/service/RemotePayFriendValidator.java): `src/main/java/com/erumpay/payment/remote/service/RemotePayFriendValidator.java`

### Live Updates

- [Dutch Live Updates](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/dutch/service/DutchPaySseService.java): `src/main/java/com/erumpay/payment/dutch/service/DutchPaySseService.java`
- [Remote Live Updates](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/remote/service/RemotePaySseService.java): `src/main/java/com/erumpay/payment/remote/service/RemotePaySseService.java`
- [Payment Notifications](https://github.com/erumpay/payment-service/blob/develop/src/main/java/com/erumpay/payment/notification/service/PaymentNotificationEventPublisher.java): `src/main/java/com/erumpay/payment/notification/service/PaymentNotificationEventPublisher.java`

### Other components

- **User**
- **Merchant Client**
- **Payment Gateway**

## Connections

- Payment Orchestration → Auth Client: calls (evidence: `src/main/java/com/erumpay/payment/core/service/CoreService.java`)
- Payment Orchestration → Card Client: calls (evidence: `src/main/java/com/erumpay/payment/core/service/CoreService.java`)
- Payment Orchestration → Gateway Client: calls (evidence: `src/main/java/com/erumpay/payment/core/service/CoreService.java`)
- Payment Orchestration → Recommendation Client: calls (evidence: `src/main/java/com/erumpay/payment/core/service/CoreService.java`)
- Payment Orchestration → Payment Records: reads/writes (evidence: `src/main/java/com/erumpay/payment/core/service/CoreService.java`)
- Payment Orchestration → Card Records: reads/writes (evidence: `src/main/java/com/erumpay/payment/core/service/CoreService.java`)
- Payment Orchestration → Payment Persistence: delegates to (evidence: `src/main/java/com/erumpay/payment/core/service/CoreService.java`)
- Payment Persistence → Payment Records: reads/writes (evidence: `src/main/java/com/erumpay/payment/core/service/CorePgPaymentPersistenceService.java`)
- Merchant Payments → Payment Records: reads/writes (evidence: `src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java`)
- Merchant Payments → Card Records: reads (evidence: `src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java`)
- Merchant Payments → Gateway Client: calls (evidence: `src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java`)
- Merchant Payments → Merchant Lookup: calls (evidence: `src/main/java/com/erumpay/payment/merchant/service/MerchantPaymentService.java`)
- QR Checkout → Payment Records: reads/writes (evidence: `src/main/java/com/erumpay/payment/qr/service/QrService.java`)
- QR Checkout → QR Records: reads/writes (evidence: `src/main/java/com/erumpay/payment/qr/service/QrService.java`)
- QR Checkout → Payment Persistence: delegates to (evidence: `src/main/java/com/erumpay/payment/qr/service/QrService.java`)
- QR Checkout → Merchant Lookup: calls (evidence: `src/main/java/com/erumpay/payment/qr/service/QrService.java`)
- Dutch Payments → Payment Records: reads/writes (evidence: `src/main/java/com/erumpay/payment/dutch/service/DutchPayService.java`)
- Dutch Payments → Dutch Sessions: reads/writes (evidence: `src/main/java/com/erumpay/payment/dutch/service/DutchPayService.java`)
- Dutch Payments → Participants: reads/writes (evidence: `src/main/java/com/erumpay/payment/dutch/service/DutchPayService.java`)
- Dutch Payments → Dutch Live Updates: publishes updates (evidence: `src/main/java/com/erumpay/payment/dutch/service/DutchPayService.java`)
- Remote Payments → Payment Records: reads (evidence: `src/main/java/com/erumpay/payment/remote/service/RemotePayService.java`)
- Remote Payments → Remote Requests: reads/writes (evidence: `src/main/java/com/erumpay/payment/remote/service/RemotePayService.java`)
- Remote Payments → Friend Validator: calls (evidence: `src/main/java/com/erumpay/payment/remote/service/RemotePayService.java`)
- Remote Payments → Remote Live Updates: publishes updates (evidence: `src/main/java/com/erumpay/payment/remote/service/RemotePayService.java`)
- Remote Payments → Payment Notifications: publishes events (evidence: `src/main/java/com/erumpay/payment/remote/service/RemotePayService.java`)
- Dutch Live Updates → Dutch Sessions: reads (evidence: `src/main/java/com/erumpay/payment/dutch/service/DutchPaySseService.java`)
- Dutch Live Updates → Participants: reads (evidence: `src/main/java/com/erumpay/payment/dutch/service/DutchPaySseService.java`)
- Payment Gateway → Gateway Client: payment calls
- User → Core API: requests
- User → Merchant API: requests