Safely Caching Provider-Owned Bank Directories

Avoiding stale and cross-provider reference data in financial destination flows.

Bank lists are ideal cache candidates. They are requested frequently, can be large, and usually change less often than transaction data.

They are also easy to cache incorrectly.

When a platform supports multiple payout providers, each provider may use its own bank identifiers, names, availability rules, and supported institutions. A shared bank-list cache can serve valid data from the wrong rail.

Scope the cache by provider and version

At minimum, the cache key should include:

country
provider
directory version

cache_key = f"bank-directory:{country}:{provider}:v3"

The version makes schema or normalization changes easy to deploy without waiting for old keys to expire.

Cache the provider’s canonical fields

Do not merge directories by bank name in the transfer path. Preserve the code and name returned by the provider that will validate and execute the payout.

The API can normalize field names for the client while retaining provider ownership:

{
  "provider": "selected_rail",
  "code": "provider_bank_code",
  "name": "Provider Bank Name"
}

Invalidate on configuration changes

Changing the active payout provider should not continue displaying the previous provider’s cached directory.

Provider-scoped keys reduce this risk. The dashboard should also support a controlled force refresh for operational updates.

Fetch all pages intentionally

Provider and internal directory APIs may paginate responses. Requesting an arbitrarily large page size is unreliable when the server enforces a maximum.

A client that needs the complete directory should follow pagination until next is empty or the collected count reaches the reported total. It should also stop safely if a page is unexpectedly empty.

Choose a failure policy

If the provider is unavailable, decide whether to serve the last known directory or fail the operation. Displaying stale reference data may be acceptable for browsing, but account validation should still use the active provider and return a controlled error if validation is unavailable.

The design principle

Reference data is part of the integration contract. Scope it by its source, preserve provider identifiers, paginate deliberately, and separate browsing availability from transaction validation.

A fast cache is useful only when it returns data valid for the operation that follows.