--- title: SAIF.Business.EPay.USBank architecture summary: Architectural responsibilities, boundaries, and interaction patterns. status: draft owner: SAIF last_reviewed: 2026-07-24 library: SAIF.Business.EPay.USBank reference_type: package --- # SAIF.Business.EPay.USBank architecture `SAIF.Business.EPay.USBank` combines a small BOF persistence layer with a larger SOAP-integration layer. It keeps SAIF-owned state in Oracle tables, delegates payment execution to generated US Bank and session-transfer proxies, and isolates XML parsing and configuration retrieval in dedicated helper types. ## Responsibilities - Persist SAIF-side US Bank integration records for users and nonpayment notices. - Orchestrate SOAP calls for user-profile, bank-account, recurring-payment, payment-information, and health-check operations. - Build browser-facing session-transfer posts for customer and admin flows. - Resolve configuration, biller constants, proxy credentials, and external XML-based admin/session-transfer values. - Parse callback and remittance XML into typed adapters. ## Component boundaries - `clsUSBankUser`, `clsUSBankUserCollection`, `clsUSBankNonpayNotice`, and `clsUSBankNonpayNoticeCollection` own the library's Oracle persistence footprint. - `USBankAPIs` owns request mapping, client-certificate attachment, outbound value normalization, and error/result handling for the primary US Bank SOAP endpoint. - `RemotePostFiller` owns session-transfer string retrieval and `RemotePost` payload composition for redirect-based payment flows. - `USBankCodes` and `USBankConstants` own non-code configuration retrieval from environment settings, legacy properties, and the external UNC-hosted constants file. - `RealTimePaymentConfirmation`, `RealTimeNonPaymentNotification`, `RemittanceDocument`, and `RemittedPayment` remain read-only XML adapters with no write-side effects. - `Interfaces.vb` defines caller-supplied abstractions that this library consumes but does not implement. ## Interaction model - User registration and update flows combine local user-record lookup or creation with outbound SOAP profile calls. - Bank-account and recurring-authorization flows normalize outbound payload content under [BR-011](business-rules.md#br-011-outbound-text-must-use-us-bank-safe-characters-and-lengths) and [BR-012](business-rules.md#br-012-bank-account-payloads-require-category-and-type). - Customer and admin redirect flows obtain a session-transfer token, normalize the return URL under [BR-014](business-rules.md#br-014-return-urls-are-rewritten-to-secure-saif-view-links), and post the resulting form to US Bank. - Callback and remittance readers deserialize incoming XML separately from the persistence and transport paths. ## Architecture diagram The following diagram shows the main handwritten components and the external systems they coordinate. ```mermaid flowchart TD Caller[Calling SAIF code] --> APIs[USBankAPIs] Caller --> Posts[RemotePostFiller] Caller --> Parsers[XML parser types] APIs --> UserBO[clsUSBankUser / clsUSBankUserCollection] APIs --> NoticeBO[clsUSBankNonpayNotice / clsUSBankNonpayNoticeCollection] APIs --> Gateway[US Bank SOAP gateway] Posts --> SessionSvc[SAIF session-transfer SOAP wrapper] Posts --> BrowserPost[RemotePost payload] APIs --> Config[USBankCodes / USBankConstants] Posts --> Config Config --> Env[Environment settings / Properties.xml] Config --> Constants[UNC-hosted constants XML] UserBO --> Oracle[(Oracle tables)] NoticeBO --> Oracle ``` ## Sequence diagram The following diagram shows the primary register-or-update-user path. ```mermaid sequenceDiagram participant Caller participant APIs as USBankAPIs participant UserBO as clsUSBankUser participant Gateway as US Bank SOAP participant Oracle as Oracle Caller->>APIs: Register user request APIs->>UserBO: Retrieve by policy and business-online user UserBO->>Oracle: SQL-008 lookup Oracle-->>UserBO: Existing row or no match APIs->>Gateway: AddUserProfile or UpdateUserProfile Gateway-->>APIs: Response code / payload APIs->>UserBO: Save local names or create row UserBO->>Oracle: SQL-004 insert or SQL-011 update Oracle-->>UserBO: Rows affected APIs-->>Caller: Integration result ``` ## Design constraints - The project has no in-repository `ProjectReference` dependencies; its extensibility point is package references, generated proxies, and caller-supplied interfaces. - Persistence is intentionally narrow: only `US_BANK_USER` and `US_BANK_NONPAY_NOTICE` are updated by handwritten code in this library. - Outbound address, name, and nickname data must satisfy [BR-010](business-rules.md#br-010-address-payloads-require-complete-postal-data) and [BR-011](business-rules.md#br-011-outbound-text-must-use-us-bank-safe-characters-and-lengths) before the SOAP call is sent. - Redirect flows must satisfy [BR-014](business-rules.md#br-014-return-urls-are-rewritten-to-secure-saif-view-links) and admin SSO flows must satisfy [BR-015](business-rules.md#br-015-admin-user-ids-are-adjusted-for-legacy-bank-constraints). - New or updated US Bank user profiles always apply [BR-016](business-rules.md#br-016-shared-secret-answers-use-the-policy-zip-code). - The library implements no application-level authorization checks; security relies on transport certificates, decryption helpers, proxy impersonation, and admin SSO payload construction. ## 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) - [Security and authorization](security-authorization.md) - [SQL catalog](sql/index.md) - [API reference](api/index.md) - [Configuration](configuration.md) ## Sources - `Business\SAIF.Business.EPay.USBank\USBankAPIs.vb` - `Business\SAIF.Business.EPay.USBank\RemotePostFiller.vb` - `Business\SAIF.Business.EPay.USBank\clsUSBankUser.vb` - `Business\SAIF.Business.EPay.USBank\clsUSBankUserCollection.vb` - `Business\SAIF.Business.EPay.USBank\clsUSBankNonpayNotice.vb` - `Business\SAIF.Business.EPay.USBank\Interfaces.vb` - `Business\SAIF.Business.EPay.USBank\USBankCodes.vb` - `Business\SAIF.Business.EPay.USBank\USBankConstants.vb` - `Business\SAIF.Business.EPay.USBank\RealTimePaymentConfirmation.vb` - `Business\SAIF.Business.EPay.USBank\RealTimeNonPaymentNotification.vb` - `Business\SAIF.Business.EPay.USBank\RemittanceDocument.vb` - `Business\SAIF.Business.EPay.USBank\RemittedPayment.vb` - `Business\SAIF.Business.EPay.USBank\epayWebServiceService.vb`