taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

075-wallet-bban-support.rst (4358B)

      1 DD 75: Wallet support for BBAN entry/display
      2 ############################################
      3 
      4 :Design status: Accepted
      5 :Implementation status: Partial
      6 :DD shepherd: TBD
      7 :Historical contributors: Florian Dold
      8 :First published: 2025-11-18
      9 :Last substantive change: 2025-12-16
     10 :Implementation evidence: ``taler-typescript-core`` (2025-12-04; 2026-07-18); ``taler-ios`` (2026-02-15)
     11 :Normative references: :doc:`../developer/taler-wallet-developer`, :doc:`../wallet/wallet-core`
     12 
     13 Summary
     14 =======
     15 
     16 This design document describes how wallets (wallet-core and UIs) should support
     17 the entry and display of BBANs for payto URIs with target type "iban".
     18 
     19 Motivation
     20 ==========
     21 
     22 Some countries (e.g. Hungary) still use BBANs (basic bank account numbers)
     23 instead of IBANs. These BBANs can be mapped to IBANs, but users expect being
     24 able to see and enter BBANs instead of IBANs.
     25 
     26 Requirements
     27 ============
     28 
     29 * Support for BBANs should not impact the UI for countries / deployments that only use IBAN
     30 * Logic for IBAN parsing / validation should not be duplicated in all UIs.
     31 * The underlying protocol / other wallet-core requests should still use ``payto://iban/`` and
     32   not some BBAN-specific logic.
     33 
     34 Proposed Solution
     35 =================
     36 
     37 Depending on the **wire type and currency**, wallet UIs will either show an
     38 IBAN or BBAN bank account entry/display UI element.  For the BBAN UI elements,
     39 the country will be derived from the wire type and currency.
     40 
     41 There will *not* be any change to the protocol / other wallet-core requests.
     42 Internally, the BBAN will be converted to a payto URI. A currency and a
     43 valid BBAN can always be mapped to a IBAN and vice versa.
     44 
     45 The following wire type / currency pairs must support BBAN entry:
     46 
     47 * ``iban`` / ``HUF``
     48 * dev-experiment only: ``iban`` / ``CHF``
     49 
     50 Wallet-core:
     51 
     52 * We provide two new requests to allow conversion between BBAN/IBAN:
     53 
     54   .. code::
     55 
     56     convertIbanAccountFieldToPayto({ value: string, currency: string })
     57       => | { ok: true, type: "iban" | "bban", paytoUri: string }
     58          | { ok: false }
     59 
     60     convertIbanPaytoToAccountField({ paytoUri: string  })
     61       => { type: "iban" | "bban", value: string }
     62 
     63 * The ``getDepositWireTypes`` request returns a ``preferredEntryType: "iban" | "bban"`` flag
     64   for every payto URI of target tpye ``"iban"``.
     65 
     66 In order to allow copy+pasting an IBAN into a BBAN field, ``convertIbanAccountFieldToPayto`` must
     67 also accept actual IBANs as input and convert them to a payto URI.
     68 
     69 
     70 Test Plan
     71 =========
     72 
     73 Wallet-core: Unit tests for conversion functions.
     74 
     75 Wallet UIs should either:
     76 
     77 * Use story books to test the new UI elements for BBAN display/entry.
     78 * Use a dev experiment ``taler://dev-experiment/fake-chf-bban`` to force display/entry
     79   of Swiss IBANs as BBAN.
     80 * Use a test HUF/IBAN deployment for testing (currently not provided/planned).
     81 
     82 
     83 Definition of Done
     84 ==================
     85 
     86 * [x] Implemented in wallet-core
     87 * [ ] Implemented in the Android, WebExtension and iOS wallets (iOS preparation
     88   has landed; complete cross-platform coverage was not established)
     89 * [ ] Tested in a QC session with a HUF-style deployment
     90 
     91 Alternatives
     92 ============
     93 
     94 * Require IBAN entry in Hungary
     95 
     96   * Not user-friendly
     97 
     98 * Define a new payto target type (e.g. ``hu-bban``).
     99 
    100   * The Hungarian banking system is based in SEPA/IBANs,
    101     so it doesn't make sense to treat it differently,
    102     just because the UIs in banking apps (and some bank-internal APIs)
    103     use BBANs.
    104 
    105 Drawbacks
    106 =========
    107 
    108 N/A.
    109 
    110 Discussion / Q&A
    111 ================
    112 
    113 * Should the user be able to switch between both display types?
    114 
    115   * No, we should use the form used by native banking apps in the respective country.
    116 
    117 * Can the user change the country when entering a BBAN?
    118 
    119   * No, we automatically derive the country from the currency.
    120     If the need arises in the future, the bank account entry dialogue
    121     for ``HUF/iban`` could have a "switch to IBAN entry" affordance.
    122 
    123 * Should the *exchange* return some flag to determine whether BBAN or IBANs are displayed?
    124 
    125   * Possible, but not planned. There is currently only one country that needs
    126     BBAN support and it's easy to just look at the wire type / currency to
    127     determine if BBAN or IBAN UI elements should be used. Flagging it on a
    128     per-exchange basis also is troublesome when there are multiple exchanges in
    129     the same scope with differing BBAN/IBAN flags.