Skip to content

analysis: Bridge customer transition — migrating banking setup when the operating entity changes #2295

Description

@rozagerardo

A Space's banking setup (Bridge customer, virtual accounts, IBANs) is tied to the legal entity that completed KYB. If the operating entity behind a Space changes — for example, Hypha referring a Space to a different organization, or a vertical being spun off — the question is whether the existing banking infrastructure can be preserved or must be rebuilt from scratch.

Rebuilding means new KYB, new virtual accounts, and critically new IBANs/routing numbers — which breaks any existing recurring wire instructions the Space's donors or partners have configured. Preserving continuity is therefore a meaningful product concern.

Questions to answer

  • Bridge side: does Bridge support reassigning or transferring a customer record to a different legal entity? Can the legal_name, entity details, or ownership of a customer be updated without losing the associated virtual accounts?
  • Virtual account portability: are virtual accounts (IBANs, ACH routing) permanently tied to the customer record, or are they independent primitives that could survive a customer transition?
  • Our side: if Bridge doesn't support entity transfer, what is the cleanest migration path on our end? Options to evaluate:
    • Create a new Bridge customer for the new entity, provision new VAs, deprecate the old ones — straightforward but loses IBAN continuity
    • Keep the old customer record active temporarily (dual-customer period) while the new one goes through KYB — what do we need to support this in our schema and UI?
  • Schema implications: bank_customers is keyed on (space_id, provider) — a migration creates a moment where a Space has two customer records (old + new). Does the schema handle this, or does the unique constraint block it?
  • Comms/UX: if IBANs change, the Space admin needs to notify all existing senders. Is there a flow we should support (e.g. a "transitioning" state with a cutover date displayed)?

Output

A decision on what's possible on the Bridge side, and if a migration path is feasible — a proposed flow and any schema/UI changes needed to support it cleanly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    analysisDesign research or investigation with a decision as outputbankingBridge / fiat / virtual accounts / banking

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions