taler-docs

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

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

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