---
title: SAIF.Business.Payment.EFT architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF
last_reviewed: 2026-07-24
library: SAIF.Business.Payment.EFT
reference_type: package
---

# SAIF.Business.Payment.EFT architecture

`SAIF.Business.Payment.EFT` is the primary implementation library for ACH/EFT electronic payment processing, complementing the narrower contract/eligibility-focused `SAIF.Business.Payment` library. It is the largest of the payment-domain libraries (~30 business object classes paired with collections) and has the broadest internal dependency footprint, consistent with EFT payment processing requiring access to claim, policy, provider, and ePay contexts.

## Responsibilities
- Manage bank account records, including masking and account-type classification (`clsBankAccount`).
- Determine payee and provider payment-method preferences — check, direct deposit, debit card — via `clsPaymentPreference` and `clsProviderPaymentPreference`.
- Record payee EFT authorization/consent (`clsEFTAuthorization`).
- Process and track debit-card payment enrollment requests (`clsDebitCardEnrollmentRequest`).
- Record individual payment line items and their allocation across claim/benefit categories (`clsPaymentDetail`, `clsPaymentAllocation`).
- Generate and track ACH batch/file identifiers and payment batch numbers (`clsAchFileID`, `clsPaymentBatchNumber`).
- Attach NACHA addenda records to EFT transactions (`clsPaymentAddenda`).
- Process returned/failed EFT payments and their reason/status/type classification (`clsPaymentReturn` + code tables).
- Compute dynamically calculated balance values (`DynamicallyCalculatedBalanceInfoFactory`).

## Component boundaries
- `clsBankAccount` / `clsBankAccountCollection`: concrete bank-account business object; implements `IBankAccount` (from `SAIF.Business.Payment`) and `IBusinessCriteria`.
- `clsPaymentPreference`: implements `iPaymentPreference` (from `SAIF.Business.Payment`) for claimant payment-method preference.
- `clsProviderPaymentPreference`: a second `iPaymentPreference` implementation scoped to medical/service providers.
- `clsEFTAuthorization` / `clsEFTAuthorizationCollection`: payee EFT authorization/consent records targeting the `PAYMENT_AUTHORIZATION` table.
- `clsDebitCardEnrollmentRequest` / `clsDebitCardEnrollmentRequestCollection`: debit-card enrollment tracking targeting `DEBIT_CARD_ENROLLMENT_REQUEST`.
- `clsPaymentDetail` / `clsPaymentDetailCollection`, `clsPaymentAllocation` / `clsPaymentAllocationCollection`: payment line-item and allocation records.
- `clsPaymentAddenda` / `clsPaymentAddendaCollection`: ACH/NACHA addenda records.
- `clsPaymentReturn` / `clsPaymentReturnCollection` (+ `clsPaymentReturnReasonCode`, `clsReturnStatusCode`, `clsReturnTypeCode` code tables): returned/failed EFT payment handling.
- `clsAchFileID` / `clsAchFileIDCollection`, `clsPaymentBatchNumber`: ACH batch/file and payment-batch identifier tracking.
- `clsBankAccountTransfer`, `clsPaymentAuthorizationSessionTransfer`, `clsSessionTransfer`: lighter-weight transfer/session-context DTOs.*
- Code-table lookup classes (18 classes): standard BOF code-table pattern covering all ACH/EFT reference data.
- `DynamicallyCalculatedBalanceInfo` / `DynamicallyCalculatedBalanceInfoFactory`: runtime balance calculation; not a persisted `IBusinessCriteria` object.*
- Local binary reference `Libs\SAIFEncrypt.dll`: checked-in encryption assembly, likely used for bank-account-number encryption given the domain, though no confirmed call site was found.**

## Interaction model
- Confirms the cross-library contract relationship: `clsBankAccount Implements IBankAccount` and `clsPaymentPreference`/`clsProviderPaymentPreference Implements iPaymentPreference` (both interfaces defined in `SAIF.Business.Payment`).
- All CRUD persistence flows through the standard BOF `IBusinessCriteria` pattern (`CreateSQL`/`RetrieveSQL`/`InsertSQL`/`UpdateSQL`/`DeleteSQL`) against an Oracle database, evidenced by `:``-prefixed bind-variable syntax and `NEXTVAL FROM DUAL` sequence generation across all transactional business objects.
- Has the broadest dependency footprint among payment-domain libraries — depends on Claim, Claim.Authority, Claim.Maintenance, Claim.MedicalBill, Claim.Payment, Claim.Person, EPay.USBank, Payment (contract source), Policy, Tasks, Tasks.Claim, Utilities, View.Claim, View.Policy, View.Provider, and Services.WebServices.Epay.
- The presence of `clsPaymentReturn`/return-reason/status/type code tables indicates a full ACH return-handling subsystem (NACHA return codes), a distinguishing architectural feature versus the sibling `SAIF.Business.Payment` library.
- Includes a dedicated `Tests` project (`SAIF.Business.Payment.EFT.Tests`), indicating this is a more actively tested area of the codebase.*

## Architecture diagram
The following diagram shows the high-level component grouping within the library and its position relative to the `SAIF.Business.Payment` contract library and Oracle persistence layer.

```mermaid
flowchart TD
    Contracts["SAIF.Business.Payment<br>IBankAccount / iPaymentPreference"] -.->|implements| BankAccount[clsBankAccount]
    Contracts -.->|implements| PaymentPref["clsPaymentPreference<br>clsProviderPaymentPreference"]
    Auth[clsEFTAuthorization] --> DebitCard[clsDebitCardEnrollmentRequest]
    PaymentDetail["clsPaymentDetail<br>clsPaymentAllocation"] --> Addenda[clsPaymentAddenda]
    PaymentDetail --> AchFile["clsAchFileID<br>clsPaymentBatchNumber"]
    PaymentDetail --> Return["clsPaymentReturn<br>+ reason/status/type code tables"]
    Encrypt["Libs/SAIFEncrypt.dll"] -.->|data protection**| BankAccount
    Framework["SAIF.BOF.Framework<br>clsBusinessBase"] --> BankAccount
    Framework --> PaymentDetail
    BankAccount --> DB[(Oracle database)]
    PaymentDetail --> DB
    Return --> DB
    Auth --> DB
```

## Sequence diagram
The following diagram shows the primary EFT payment-processing sequence from authorization through payment-detail persistence.

```mermaid
sequenceDiagram
    participant Caller
    participant EFTAuth as clsEFTAuthorization
    participant BankAccount as clsBankAccount
    participant PaymentDetail as clsPaymentDetail
    participant Oracle as Oracle database
    Caller->>EFTAuth: Verify/create authorization
    EFTAuth->>Oracle: Execute RetrieveSQL / InsertSQL
    Caller->>BankAccount: Retrieve bank account
    BankAccount->>Oracle: Execute RetrieveSQL
    Caller->>PaymentDetail: Create payment detail
    PaymentDetail->>Oracle: Execute CreateSQL (NEXTVAL FROM DUAL)
    Oracle-->>PaymentDetail: Sequence value
    PaymentDetail->>Oracle: Execute InsertSQL
    Oracle-->>PaymentDetail: Row count / confirmation
    PaymentDetail-->>Caller: Persisted payment detail
```

## Design constraints
- Targets Oracle exclusively; no other database provider evidence was found.
- No AD/authorization-framework interaction was detected; however, the `Libs\SAIFEncrypt.dll` reference is a data-protection consideration given the sensitivity of bank routing/account numbers handled here.**
- No configuration framework (`IEnvironmentService`, `ConfigurationManager.AppSettings`, `DbConnectionManager`) interaction was detected.
- Dependencies are resolved entirely as NuGet package references per the `.nuspec` plus one local binary reference (`Libs\SAIFEncrypt.dll`); no local `<ProjectReference>`s were found.
- This is the only one of the 5 assigned libraries with a dedicated `Tests` project, indicating a more actively/rigorously tested area of the codebase.*

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with `**` could not be confirmed; treat as unknown until verified.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [API reference](api/index.md)
- [Configuration](configuration.md)

## Sources
- `Business\SAIF.Business.Payment.EFT\clsBankAccount.vb`
- `Business\SAIF.Business.Payment.EFT\clsPaymentPreference.vb`
- `Business\SAIF.Business.Payment.EFT\clsProviderPaymentPreference.vb`
- `Business\SAIF.Business.Payment.EFT\clsEFTAuthorization.vb`
- `Business\SAIF.Business.Payment.EFT\clsDebitCardEnrollmentRequest.vb`
- `Business\SAIF.Business.Payment.EFT\clsPaymentDetail.vb`
- `Business\SAIF.Business.Payment.EFT\clsPaymentAllocation.vb`
- `Business\SAIF.Business.Payment.EFT\clsPaymentAddenda.vb`
- `Business\SAIF.Business.Payment.EFT\clsPaymentReturn.vb`
- `Business\SAIF.Business.Payment.EFT\clsAchFileID.vb`
- `Business\SAIF.Business.Payment.EFT\clsPaymentBatchNumber.vb`
- `Business\SAIF.Business.Payment.EFT\DynamicallyCalculatedBalanceInfo.vb`
- `Business\SAIF.Business.Payment.EFT\DynamicallyCalculatedBalanceInfoFactory.vb`
- `Business\SAIF.Business.Payment.EFT\Libs\SAIFEncrypt.dll`
- `Business\SAIF.Business.Payment.EFT\Tests\PaymentDetailTests.vb`
- `Business\SAIF.Business.Payment.EFT\SAIF.BOF.Business.Payment.EFT.nuspec`