DD 75: Wallet support for BBAN entry/display

14.75. DD 75: Wallet support for BBAN entry/display#

14.75.1. Summary#

This design document describes how wallets (wallet-core and UIs) should support the entry and display of BBANs for payto URIs with target type “iban”.

14.75.2. Motivation#

Some countries (e.g. Hungary) still use BBANs (basic bank account numbers) instead of IBANs. These BBANs can be mapped to IBANs, but users expect being able to see and enter BBANs instead of IBANs.

14.75.3. Requirements#

  • Support for BBANs should not impact the UI for countries / deployments that only use IBAN

  • Logic for IBAN parsing / validation should not be duplicated in all UIs.

  • The underlying protocol / other wallet-core requests should still use payto://iban/ and not some BBAN-specific logic.

14.75.4. Proposed Solution#

Depending on the wire type and currency, wallet UIs will either show an IBAN or BBAN bank account entry/display UI element. For the BBAN UI elements, the country will be derived from the wire type and currency.

There will not be any change to the protocol / other wallet-core requests. Internally, the BBAN will be converted to a payto URI. A country code (for countries that need BBAN support) and a valid BBAN can always be mapped to a IBAN and vice versa.

The following wire type / currency pairs must support BBAN entry:

  • iban / HUF

  • feature flag only: iban / CHF

Wallet-core:

  • We provide two new requests to allow conversion between BBAN/IBAN:

    • convertBbanToPaytoIban({ bban: string, currency: string }) -> { paytoUri: string }

    • convertPaytoIbanToBban({ paytoUri: string  }) -> { bban: string }

In order to allow copy+pasting an IBAN into a BBAN field, the convertBbanToPaytoIban should also accept actual IBANs as input and convert them to a payto URI.

14.75.5. Test Plan#

Wallet-core: Unit tests for conversion functions.

Wallet UIs should either:

  • Use story books to test the new UI elements for BBAN display/entry.

  • Use a feature flag to test the BBAN display with rusty and CHF

  • Use a test HUF/IBAM deployment for testing (currently not provided/planned).

14.75.6. Definition of Done#

  • Implemented in wallet-core

  • Implemented in the Android, webext and iOS wallets

  • Tested in a QC session with a HUF-style deployment

14.75.7. Alternatives#

  • Require IBAN entry in Hungary

    • Not user-friendly

  • Define a new payto target type (e.g. hu-bban).

    • The Hungarian banking system is based in SEPA/IBANs, so it doesn’t make sense to treat it differently, just because the UIs in banking apps (and some bank-internal APIs) use BBANs.

14.75.8. Drawbacks#

N/A.

14.75.9. Discussion / Q&A#

  • Should the user be able to switch between both display types?

    • No, we should use the form used by native banking apps in the respective country.

  • Can the user change the country when entering a BBAN?

    • No, we automatically derive the country from the currency. If the need arises in the future, the bank account entry dialogue for HUF/iban could have a “switch to IBAN entry” affordance.

  • Should the exchange return some flag to determine whether BBAN or IBANs are displayed?

    • Possible, but not planned. There is currently only one country that needs BBAN support and it’s easy to just look at the wire type / currency to determine if BBAN or IBAN UI elements should be used. Flagging it on a per-exchange basis also is troublesome when there are multiple exchanges in the same scope with differing BBAN/IBAN flags.