# nb-sb/epay-sdk architecture

> Architecture diagram of the GitHub repository nb-sb/epay-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nb-sb/epay-sdk
- Repository: https://github.com/nb-sb/epay-sdk

## Overview

epay-sdk is a Java client for Rainbow Epay gateways, supporting V1/MD5, V2/RSA, and the legacy MZF dialect; a Spring Boot starter supplies auto-configuration. The principal workflow is application code building a payment request, EPayClient selecting and invoking a protocol adapter, and that adapter using the transport boundary to communicate with the gateway and return a typed result. The API also covers order queries, notifications, refunds, merchant queries, and order listing. Adapter implementations and polling internals were not fully excerpted, so some subsystem links are documented or marked unverified rather than inferred as calls.

Main entry points: [`epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java) (EPay Client), [`epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolContext.java`](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolContext.java) (Request Context), [`epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayAutoConfiguration.java`](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayAutoConfiguration.java) (Spring Boot Setup), [`epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv1/EpayV1Adapter.java`](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv1/EpayV1Adapter.java) (Epay V1 Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Application Integration"]
  node_spring["Spring Boot Setup"]
  node_properties["Epay Properties"]
end

subgraph group_api["Client API"]
  node_client["EPay Client<br/>[EPayClient.java]"]
  node_api_contract["Payment API<br/>[EPay.java]"]
  node_poller["Order Poller<br/>[OrderPoller.java]"]
  node_payment_models["Payment Models"]
  node_order_models["Order Models"]
  node_notification_models["Notification Models"]
  node_refund_models["Refund Models<br/>[RefundRequest.java]"]
  node_result_models["Gateway Results<br/>[GatewayResult.java]"]
  node_errors["SDK Errors<br/>[EPayException.java]"]
end

subgraph group_protocol["Gateway Protocols"]
  node_v1["Epay V1 Adapter<br/>[EpayV1Adapter.java]"]
  node_v2["Epay V2 Adapter<br/>[EpayV2Adapter.java]"]
  node_mzf["MZF Adapter"]
  node_protocol_spi["Adapter SPI"]
end

subgraph group_runtime["Transport Runtime"]
  node_context["Request Context"]
  node_http_spi["HTTP Transport SPI<br/>[HttpTransport.java]"]
  node_apache_http["Apache HTTP"]
  node_checks["Input Checks<br/>[Checks.java]"]
end

node_app(("Merchant Application"))
node_gateway(("Epay Gateway"))

node_app -->|"builds and calls"| node_client
node_app -.->|"configures through"| node_spring
node_spring -->|"binds properties"| node_properties
node_spring -->|"creates client"| node_client
node_client -->|"implements"| node_api_contract
node_client -->|"selects adapter"| node_v1
node_client -->|"selects adapter"| node_v2
node_client -->|"registers adapter"| node_mzf
node_client -->|"dispatches operations"| node_protocol_spi
node_client -->|"creates default transport"| node_apache_http
node_client -.->|"polls orders"| node_poller
node_v1 -->|"uses request context"| node_context
node_v2 -->|"uses request context"| node_context
node_context -->|"sends requests"| node_http_spi
node_apache_http -.->|"sends HTTP"| node_gateway
node_client -->|"accepts payment request"| node_payment_models
node_client -->|"accepts order reference"| node_order_models
node_client -->|"accepts notification"| node_notification_models
node_client -->|"accepts refund request"| node_refund_models
node_client -->|"returns gateway result"| node_result_models
node_context -->|"validates inputs"| node_checks

click node_spring "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayAutoConfiguration.java"
click node_properties "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayProperties.java"
click node_client "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java"
click node_api_contract "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPay.java"
click node_poller "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/OrderPoller.java"
click node_payment_models "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/PaymentRequest.java"
click node_order_models "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/OrderReference.java"
click node_notification_models "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/NotificationRequest.java"
click node_refund_models "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/RefundRequest.java"
click node_result_models "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/GatewayResult.java"
click node_errors "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayException.java"
click node_v1 "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv1/EpayV1Adapter.java"
click node_v2 "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv2/EpayV2Adapter.java"
click node_mzf "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/mzf/MzfLegacyAdapter.java"
click node_protocol_spi "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolAdapter.java"
click node_context "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolContext.java"
click node_http_spi "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/spi/HttpTransport.java"
click node_apache_http "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/internal/ApacheHttpTransport.java"
click node_checks "https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/internal/checks/Checks.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_spring,node_properties toneBlue
class node_client,node_api_contract,node_poller,node_payment_models,node_order_models,node_notification_models,node_refund_models,node_result_models,node_errors toneAmber
class node_v1,node_v2,node_mzf,node_protocol_spi toneMint
class node_context,node_http_spi,node_apache_http,node_checks toneRose
class node_app,node_gateway toneIndigo
```

## Components

### Application Integration

- [Spring Boot Setup](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayAutoConfiguration.java): `epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayAutoConfiguration.java`
- [Epay Properties](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayProperties.java): `epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayProperties.java`

### Client API

- [EPay Client](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`
- [Payment API](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPay.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPay.java`
- [Order Poller](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/OrderPoller.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/api/OrderPoller.java`
- [Payment Models](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/PaymentRequest.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/model/PaymentRequest.java`
- [Order Models](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/OrderReference.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/model/OrderReference.java`
- [Notification Models](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/NotificationRequest.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/model/NotificationRequest.java`
- [Refund Models](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/RefundRequest.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/model/RefundRequest.java`
- [Gateway Results](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/model/GatewayResult.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/model/GatewayResult.java`
- [SDK Errors](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayException.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayException.java`

### Gateway Protocols

- [Epay V1 Adapter](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv1/EpayV1Adapter.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv1/EpayV1Adapter.java`
- [Epay V2 Adapter](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv2/EpayV2Adapter.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv2/EpayV2Adapter.java`
- [MZF Adapter](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/mzf/MzfLegacyAdapter.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/mzf/MzfLegacyAdapter.java`
- [Adapter SPI](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolAdapter.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolAdapter.java`

### Transport Runtime

- [Request Context](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolContext.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolContext.java`
- [HTTP Transport SPI](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/spi/HttpTransport.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/spi/HttpTransport.java`
- [Apache HTTP](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/internal/ApacheHttpTransport.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/internal/ApacheHttpTransport.java`
- [Input Checks](https://github.com/nb-sb/epay-sdk/blob/main/epay-sdk/src/main/java/com/nbsb/epaysdk/internal/checks/Checks.java): `epay-sdk/src/main/java/com/nbsb/epaysdk/internal/checks/Checks.java`

### Other components

- **Merchant Application**
- **Epay Gateway**

## Connections

- Merchant Application → EPay Client: builds and calls (evidence: `README.md`)
- Merchant Application → Spring Boot Setup: configures through
- Spring Boot Setup → Epay Properties: binds properties (evidence: `epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayAutoConfiguration.java`)
- Spring Boot Setup → EPay Client: creates client (evidence: `epay-sdk-spring-boot-starter/src/main/java/com/nbsb/epaysdk/spring/EPayAutoConfiguration.java`)
- EPay Client → Payment API: implements (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Epay V1 Adapter: selects adapter (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Epay V2 Adapter: selects adapter (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → MZF Adapter: registers adapter (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Adapter SPI: dispatches operations (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Apache HTTP: creates default transport (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Order Poller: polls orders (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/OrderPoller.java`)
- Epay V1 Adapter → Request Context: uses request context (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv1/EpayV1Adapter.java`)
- Epay V2 Adapter → Request Context: uses request context (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/protocol/epayv2/EpayV2Adapter.java`)
- Request Context → HTTP Transport SPI: sends requests (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolContext.java`)
- Apache HTTP → Epay Gateway: sends HTTP
- EPay Client → Payment Models: accepts payment request (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Order Models: accepts order reference (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Notification Models: accepts notification (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Refund Models: accepts refund request (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- EPay Client → Gateway Results: returns gateway result (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/api/EPayClient.java`)
- Request Context → Input Checks: validates inputs (evidence: `epay-sdk/src/main/java/com/nbsb/epaysdk/spi/ProtocolContext.java`)