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

# SAIF.Business.Provider.PaymentPreference architecture

`SAIF.Business.Provider.PaymentPreference` is a mid-tier BOF class library that manages provider payment-preference data: paperless EOB (Explanation of Benefits) delivery preferences, EFT (Electronic Funds Transfer / direct-deposit) interface records, and a read-only view of provider bank accounts. It sits between Oracle data access (via the BOF Data Portal) and upper-tier application/service layers.

## Responsibilities
- Manage `clsProviderEOB`/`clsProviderEOBCollection` — the external user's paperless-EOB delivery preference for a provider location, including insert/update/delete against `PROVIDER_EOB_INTERFACE` with optimistic concurrency.
- Manage `clsProviderEFT`/`clsProviderEFTCollection` — the EFT interface record linking a provider location to an external user type, with effective/expiry date tracking, assignment/revocation of `clsProviderPaymentPreference` child objects, and correspondence-history recording via the `PK83548_PROVIDER_CORR_HIST.EFT_CORR_HIST` stored procedure.
- Provide `clsProviderBankAccount`/`clsProviderBankAccountCollection` — a read-only view of bank accounts associated with a provider, decrypting sensitive bank routing/account numbers on demand via `SAIF.Security.clsSecureEncrypt`.
- Support batch processing (e.g., ACH direct-deposit status updates) via `clsProviderEFTCollection.GetAllEFTsColl`, an unfiltered full-table retrieval of `PROVIDER_EFT_INTERFACE`.*

## Component boundaries
- **EOB preference component (`clsProviderEOB`/`clsProviderEOBCollection`)** — Owns `PROVIDER_EOB_INTERFACE` CRUD, joined with `EXT_USER_TYPE`, `EXT_USER`, `EMAIL_ADDRESS`, `PERSON` for display context.
- **EFT preference component (`clsProviderEFT`/`clsProviderEFTCollection`)** — Owns `PROVIDER_EFT_INTERFACE` CRUD and orchestrates the child `clsProviderPaymentPreference` object (from the peer `SAIF.BOF.Business.Payment.EFT` package) through `AddChildObject`, `SaveChildObject`, and `RevokeAuthorization`.
- **Bank account view component (`clsProviderBankAccount`/`clsProviderBankAccountCollection`)** — Read-only; its `Criteria.RetrieveSQL` throws, so retrieval must go through the collection's `Load()` path rather than `RetrieveObject`.*
- **Stored procedure integration** — `clsProviderEFT.CreateHistory` calls the Oracle package procedure `PK83548_PROVIDER_CORR_HIST.EFT_CORR_HIST` (schema `WCIS_DBA`) to persist correspondence history; procedure-level business rules and operations ([PBR-001](business-rules.md#pbr-001-only-the-provider-primary-tax-id-row-supplies-the-correspondence-address), [PBR-002](business-rules.md#pbr-002-the-tax-id-row-must-be-effective-on-the-supplied-eft-effective-date), [PBR-003](business-rules.md#pbr-003-fetch-tin-address-returns-only-the-first-matching-tax-id-address-row), [PBR-004](business-rules.md#pbr-004-eft-correspondence-history-inserts-are-always-marked-as-authorization-letter-events), [PBR-005](business-rules.md#pbr-005-foreign-address-history-values-are-normalized-to-y-or-n-during-insert), [PBR-006](business-rules.md#pbr-006-correspondence-history-rows-always-stamp-create-date-create-number-and-create-user), [PBR-007](business-rules.md#pbr-007-tax-id-lookup-failures-are-raised-instead-of-silently-ignored), [PBR-008](business-rules.md#pbr-008-correspondence-history-insert-failures-are-re-raised-as-the-package-local-exception)) are documented separately and feed into `business-rules.md` and `operations-processes.md`.

## Interaction model
- Callers obtain an `IDataPortalInfo` (DPI) from the application layer and invoke a static factory (e.g., `clsProviderEFTCollection.GetProviderEFTLocations(dpi, providerID, ...)`).
- The factory delegates to `IDataPortalInfo.DataAccessLayer.RetrieveObject(New Criteria(...))` or to `clsBusinessCollection.Load()` via `SqlHelper` for direct-SQL retrieval paths.
- Insert/Update/Delete follow the standard BOF `Before*`/`After*` lifecycle, with `AfterInsert`/`AfterUpdate` checking `RowsAffected = 1` for concurrency validation and raising `InsertError`/`DBContentionError` on failure.
- `clsProviderEFT.ProviderPaymentPreference` lazy-loads a `clsProviderPaymentPreference` child object from `SAIF.BOF.Business.Payment.EFT`; EFT authorization changes cascade to this child object.
- `clsProviderBankAccount` delegates to `clsBankAccount.GetBankAccount()` (from `SAIF.BOF.Business.Payment`) and decrypts bank numbers via the locally referenced `SAIFEncrypt.dll` (`SAIF.Security.clsSecureEncrypt`).
- `clsProviderEFT.CreateHistory` calls the `PK83548_PROVIDER_CORR_HIST.EFT_CORR_HIST` Oracle stored procedure, which internally calls `FETCH_TIN_ADDRESS` to resolve the provider's primary tax-ID address for the history record.

## Architecture diagram
The following diagram shows the three business components and their downstream dependencies.

```mermaid
flowchart TD
	Consumer[Consuming application] --> EOB[clsProviderEOB /<br>clsProviderEOBCollection]
	Consumer --> EFT[clsProviderEFT /<br>clsProviderEFTCollection]
	Consumer --> BankAcct[clsProviderBankAccount /<br>clsProviderBankAccountCollection]
	EOB --> Oracle[(Oracle database<br>PROVIDER_EOB_INTERFACE, EXT_USER, PERSON)]
	EFT --> Oracle2[(Oracle database<br>PROVIDER_EFT_INTERFACE, PROVIDER_LOCATION)]
	EFT --> PaymentPref[clsProviderPaymentPreference<br>SAIF.BOF.Business.Payment.EFT]
	EFT --> StoredProc[PK83548_PROVIDER_CORR_HIST.EFT_CORR_HIST<br>Oracle stored procedure]
	BankAcct --> BankAccount[clsBankAccount<br>SAIF.BOF.Business.Payment]
	BankAcct --> Encrypt[SAIFEncrypt.dll<br>clsSecureEncrypt]
	BankAcct --> Oracle3[(Oracle database<br>BANK_ACCOUNT, PAYMENT_AUTHORIZATION)]
```

## Sequence diagram
The following sequence diagram shows EFT payment-location assignment.

```mermaid
sequenceDiagram
	participant Consumer as Consuming application
	participant EFT as clsProviderEFT
	participant PaymentPref as clsProviderPaymentPreference
	participant Oracle as Oracle database
	Consumer->>EFT: AssignPaymentLocation
	EFT->>PaymentPref: revoke existing authorization (if Direct Deposit and saved)
	EFT->>Oracle: BeforeUpdate/BeforeInsert SQL
	Oracle-->>EFT: RowsAffected
	EFT->>PaymentPref: SaveChildObject
	EFT-->>Consumer: CustomerEmailNotificationFlag set, notification pending
```

## Design constraints
- `clsProviderBankAccount.Criteria.RetrieveSQL` throws `ApplicationException`; the safe retrieval path is `Load()` via the collection rather than `GetProviderBankAccount`/`NewProviderBankAccount` factories, which would throw at runtime if used.*
- No `IEnvironmentService`, `ConfigurationManager.AppSettings`, or application-level configuration keys were found; Oracle connection selection is externalized via `IDataPortalInfo`.*
- Several claim-layer and policy-layer NuGet packages (`SAIF.BOF.Business.Claim.*`, `SAIF.BOF.Business.Policy`, `SAIF.BOF.Business.Tasks.*`) are declared in `packages.config`/`.nuspec` but have no direct usage found in the four primary source files; their inclusion may be transitive or legacy.**
- `SAIFEncrypt.dll` is referenced as a locally-committed DLL (`..\..\Libs\SAIFEncrypt\SAIFEncrypt.dll`), not a NuGet package; its version, ownership, and update process are unknown.**
- `clsProviderEFT.CreateHistory` always returns `True` regardless of the stored procedure outcome; whether the procedure raises exceptions or status codes that should be checked is unconfirmed.*
- `clsProviderEFTCollection.GetAllEFTsColl` performs an unfiltered full-table scan of `PROVIDER_EFT_INTERFACE` for ACH batch processing, a potential performance concern at scale.**

## Correspondence-history sequence
The following sequence diagram shows EFT correspondence-history creation.

```mermaid
sequenceDiagram
    participant Consumer as Consuming application
    participant EFT as clsProviderEFT
    participant Proc as PK83548_PROVIDER_CORR_HIST
    participant Oracle as Oracle database
    Consumer->>EFT: CreateHistory()
    EFT->>Proc: EFT_CORR_HIST(parameters)
    Proc->>Oracle: SELECT PROVIDER / PROVIDER_TAX_ID
    Proc->>Oracle: INSERT PROVIDER_CORR_HIST
    Proc-->>EFT: Procedure completes
    EFT-->>Consumer: True
```

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

> **Note:** Statements marked with `*` are inferred from code behavior rather than explicit documentation or comments; statements marked with `**` could not be confirmed and should be treated as unknown until verified.

## Sources
- `Business\SAIF.Business.Provider.PaymentPreference\clsProviderEOB.vb`
- `Business\SAIF.Business.Provider.PaymentPreference\clsProviderEOBCollection.vb`
- `Business\SAIF.Business.Provider.PaymentPreference\clsProviderEFT.vb`
- `Business\SAIF.Business.Provider.PaymentPreference\clsProviderBankAccounts.vb`
- `Business\SAIF.Business.Provider.PaymentPreference\SAIF.BOF.Business.Provider.PaymentPreference.vbproj`