---
title: Bank detail retrieval
summary: Fetches bank-detail XML, an unaggregated bank list, or a typed Institutions DataSet for a routing number from the ABA vendor service.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: BankValidator
reference_type: package
operation_id: OP-BV-03
trigger: Caller invokes GetBankFullXML, GetBankListXML, or GetBankFullDS
---

# Bank detail retrieval

This operation covers the three façade methods that retrieve bank-detail data for a routing number from the ABA vendor service: `GetBankFullXML` and `GetBankListXML` return raw XML payloads, while `GetBankFullDS` additionally parses the full-detail XML into the generated `Institutions` typed `DataSet`. All three are the only operations in this library that treat a vendor `SoapException` as a not-found condition rather than an error.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-BV-03 |
| **Trigger** | Caller calls `GetBankFullXML(inRoutingNum)`, `GetBankListXML(inRoutingNum)`, or `GetBankFullDS(inRoutingNum)` on a constructed `clsValidateBank` |
| **Inputs** | `inRoutingNum` (routing number string) |
| **Outputs** | XML string (`GetBankFullXML`, `GetBankListXML`) or a populated/empty `Institutions` `DataSet` (`GetBankFullDS`) |
| **Primary components** | `clsValidateBank.GetBankFullXML`, `clsValidateBank.GetBankListXML`, `clsValidateBank.GetBankFullDS`, `clsValidateBank.LogonABA`, `clsValidateBank.LogoffABA`, `SAIF.Institutions` |
| **Entry point** | `Legacy\BankValidator\clsValidateBank.vb` |

## Steps

1. **Log on to the ABA service.** `LogonABA()` increments `m_LogonAttempts`, lazily constructs `ABAService.ABAService` if needed, sets its `Url` from `URLABA`, and calls `ABA.Logon(CompanyId, UserId, Password)` to obtain a `LogonToken` ([BR-002](../business-rules.md#br-002-vendor-logon-retry-handling)). This call is wrapped in the outer `Try` block for all three methods.
   - On failure inside `LogonABA`: recursively retries while `m_LogonAttempts < m_LogonAttemptsMax`, then throws `ApplicationException("Unable to logon to ABA web service.", ex)` once exhausted.
2. **Invoke the vendor retrieval.**
   - For `GetBankFullXML` and `GetBankFullDS`: call `ABA.GetBanksFullXML(LogonToken, inRoutingNum)` and assign the result to `bankXML`.
   - For `GetBankListXML`: call `ABA.GetBanksXML(LogonToken, inRoutingNum)` and assign the result to `bankXML`.
3. **Parse into a DataSet (`GetBankFullDS` only).** If `bankXML.Length > 0`, construct a `System.IO.StringReader` over `bankXML` and call `dsBank.ReadXml(xmlSR, XmlReadMode.ReadSchema)` to populate the `Institutions` DataSet.*
   - If `bankXML` is empty, the `Institutions` DataSet is returned unpopulated.
4. **Handle a vendor not-found fault.** If `System.Web.Services.Protocols.SoapException` is raised by the ABA call, the method treats it as a not-found condition and assigns `bankXML = ""` ([BR-003](../business-rules.md#br-003-bank-lookup-soap-faults-return-empty-results)).
   - For `GetBankFullXML` and `GetBankListXML`: the empty string is returned directly.
   - For `GetBankFullDS`: because the fault short-circuits before step 3, the `Institutions` DataSet remains unpopulated and is returned empty.
5. **Handle any other exception.** Any exception other than `SoapException` is re-thrown as `ApplicationException("Error while trying to get the bank info", ex)`.
6. **Log off the ABA service.** All three methods call `LogoffABA()` in a `Finally` block, guaranteeing the ABA proxy is disposed and the session token released regardless of whether step 2–5 succeeded, faulted, or threw.
   - On a `LogoffABA` failure: the exception is silently swallowed (the `Throw` line is commented out).
7. **Return the result.** `GetBankFullXML` and `GetBankListXML` return the `bankXML` string; `GetBankFullDS` returns the `dsBank` `Institutions` DataSet.

## Process flow

The following diagram visualizes the shared control flow, including the SoapException fault path that differs from the other operations in this library.

```mermaid
flowchart TD
	Start([Caller calls GetBankFullXML,<br>GetBankListXML, or GetBankFullDS]) --> Logon[LogonABA:<br>logon with retry up to m_LogonAttemptsMax]
	Logon --> LogonOk{Logon succeeded?}
	LogonOk -->|No, retries exhausted| Ex([ApplicationException thrown])
	LogonOk -->|Yes| Which{Which method?}
	Which -->|GetBankFullXML / GetBankFullDS| Full[ABA.GetBanksFullXML]
	Which -->|GetBankListXML| ListCall[ABA.GetBanksXML]
	Full --> Fault{SoapException?}
	ListCall --> Fault
	Fault -->|Yes| Empty[bankXML = empty string]
	Fault -->|No, other exception| OtherEx([ApplicationException thrown])
	Fault -->|No| HasXml{bankXML.Length > 0<br>and GetBankFullDS?}
	HasXml -->|Yes| Parse[ReadXml into<br>Institutions DataSet]
	HasXml -->|No| Skip[No parsing]
	Empty --> Logoff[LogoffABA in Finally:<br>release token, dispose proxy]
	Parse --> Logoff
	Skip --> Logoff
	Logoff --> Done([Return XML string<br>or Institutions DataSet])
```

## Failure and edge-case behavior
- A vendor `SoapException` is treated uniformly across all three methods as a not-found condition, returning an empty string or an unpopulated `Institutions` DataSet instead of propagating the fault ([BR-003](../business-rules.md#br-003-bank-lookup-soap-faults-return-empty-results)).
- Any non-`SoapException` failure is wrapped and re-thrown as `ApplicationException("Error while trying to get the bank info", ex)`, unlike the ABA validation and lookup operations, which let vendor exceptions propagate unmodified.
- `LogoffABA` is guaranteed to run via `Finally` for all three methods, so — unlike ABA routing number validation and company identifier lookup — the ABA proxy is always released even when the vendor call faults.
- A source comment on `GetBankFullDS` states "for some reason this function never loads the data into the dataset," while the active (non-commented) code path does call `dsBank.ReadXml(...)`; whether the DataSet is reliably populated at runtime could not be confirmed from source alone.**
- `GetBankFullDS` retains commented-out code for an alternative XML-to-DataSet loading approach (`domBank.LoadXml` / `CType(domBank.DataSet, ...)`); this dead code is not part of the executed logic and is excluded from the steps above.
- `LogoffABA` failures are intentionally swallowed and never surface to the caller.*

> **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
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `Legacy\BankValidator\clsValidateBank.vb`
- `Legacy\BankValidator\Institutions.Designer.vb`