commit 360c79a02b8fe5ef67d84e6acea76743422d7035
parent 375d226439e8728dd2262e0499d41d65db998f7c
Author: Florian Dold <florian@dold.me>
Date: Tue, 18 Nov 2025 14:58:09 +0100
DD75
Diffstat:
2 files changed, 91 insertions(+), 0 deletions(-)
diff --git a/design-documents/075-wallet-bban-support.rst b/design-documents/075-wallet-bban-support.rst
@@ -0,0 +1,90 @@
+DD XY: Wallet support for BBAN entry/display
+############################################
+
+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".
+
+Motivation
+==========
+
+Some countries (e.g. Hungary) still use BBANs instead of IBANs. These BBANs can
+be mapped to IBANs, but users expect being able to see and enter BBANs instead
+of IBANs.
+
+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.
+
+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.
+
+The following wire type / currency pairs must support BBAN entry:
+
+* ``iban`` / ``HUF`` => country code ``HU``
+* feature flag only: ``iban`` / ``CHF`` => country code ``CH``
+
+Wallet-core:
+
+* We provide two new requests to allow conversion between BBAN/IBAN:
+
+ * ``convertBbanToPaytoIban({ bban: string, country: string }) -> { paytoUri: string }``
+ * ``convertPaytoIbanToBban({ paytoUri: string }) -> { bban: string }``
+
+
+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).
+
+
+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
+
+Alternatives
+============
+
+* Require IBAN entry in Hungary
+
+ * Not user-friendly
+
+* Define a new payto target type (``hu-bban``).
+
+Drawbacks
+=========
+
+N/A.
+
+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.
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -86,4 +86,5 @@ Design documents that start with "XX" are considered deprecated.
072-products-units
073-extended-merchant-template
074-merchant-backend-simplification
+ 075-wallet-bban-support
999-template
