taler-docs

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

074-merchant-backend-simplification.rst (10923B)


      1 DD 74: Merchant Backend Simplification
      2 ######################################
      3 
      4 :Design status: Draft
      5 :Implementation status: Not started
      6 :DD shepherd: TBD
      7 :Historical contributors: Florian Dold, Christian Grothoff, Sebastian
      8 :First published: 2025-11-13
      9 :Last substantive change: 2026-02-05
     10 
     11 Summary
     12 =======
     13 
     14 This design document proposes simplifications to the merchant backend user interface.
     15 
     16 Motivation
     17 ==========
     18 
     19 The current merchant backend SPA provides a user interface tailored towards
     20 expert users that know the underlying protocol concepts.
     21 
     22 Requirements
     23 ============
     24 
     25 * The merchant backend SPA should be usable by non-experts
     26 * Different normal users will have different use-cases, requirements
     27   and background, so one-size-fits-all does not apply.
     28 * The merchant backend SPA should remain as a tool for expert users
     29 * We do not want to maintain different versions of the merchant backend SPA
     30 
     31 
     32 Proposed Solution (Iteration 1)
     33 ===============================
     34 
     35 Existing Pages
     36 ^^^^^^^^^^^^^^
     37 
     38 What follows is a listing of the menu entries
     39 in the merchant UI as of 2025-11-13.  It serves as the
     40 basis of further discussion in this document.
     41 
     42 
     43 Top-Level (unnamed)
     44 
     45 * Orders
     46 * Inventory
     47 * Categories
     48 * Wire transfers
     49 * Templates
     50 * KYC Status
     51 
     52 Configuration:
     53 
     54 * Bank accounts
     55 * OTP Devices
     56 * Webhooks
     57 * Settings
     58 * Password
     59 * Access tokens
     60 
     61 Connection:
     62 
     63 * Interface
     64 
     65 Instances:
     66 
     67 * New
     68 * List
     69 * Logout
     70 
     71 
     72 Personas
     73 ^^^^^^^^
     74 
     75 * Personas are a preset of feature flags and other settings
     76 * The backend provides a default persona.  After login, the UI for
     77   this persona is chosen. It can be changed in the "Personalization" menu.
     78 * We do not call it "profiles", because it clashes with the "profile" terminology
     79   as it is typically used in UIs (contact info, profile picture, ...).
     80 
     81 
     82 Persona Definitions
     83 ^^^^^^^^^^^^^^^^^^^
     84 
     85 * ``Beta tester``
     86 
     87   * Every feature flag on
     88   * Should come last in the drop-down
     89 
     90 * ``Expert``
     91 
     92   * All basic features
     93   * Second to last in dropdown
     94   * No Age restriction
     95   * No token families
     96   * No product taxes
     97   * No refreshable scopes
     98 
     99 * ``Unattended in-person offline vending`` (minimal farm shop) showing:
    100 
    101   * ``Orders``, but exclude ``+``-button for creating new orders manually,
    102     that's already a power-user feature.
    103 
    104   * ``Templates``, but exclude OTP devices, only useful for power-users.
    105 
    106   * ``KYC status`` (but only if action required)
    107 
    108   * ``Bank accounts``, including KYC status
    109 
    110   * ``Settings``
    111 
    112   * ``Logout``
    113 
    114 
    115 * ``Unattended in-person offline vending with inventory``,
    116   (this choice should only be enabled once we have the next
    117   version of templates with inventory!) showing:
    118 
    119   * Orders, but exclude ``+`` button for creating new orders manually,
    120     that's already a power-user feature.
    121 
    122   * ``Inventory`` (once supported by templates!)
    123 
    124   * ``Categories`` (once supported by templates!)
    125 
    126   * ``Templates``, but exclude OTP devices, again, HW doesn't exist yet,
    127         and only useful for power-users. Without age restriction and paymentTimeout option.
    128 
    129   * ``KYC status`` (if action required)
    130 
    131   * ``Bank accounts``
    132 
    133   * ``Settings``
    134 
    135   * ``Logout``
    136 
    137 * ``In-person online point-of-sale with inventory`` showing:
    138 
    139   * ``Orders``, but exclude ``+``-button for creating new orders manually,
    140     that's already a power-user feature.
    141 
    142   * ``Inventory``
    143 
    144   * ``Categories``
    145 
    146   * ``Access tokens``
    147 
    148   * ``KYC status`` (if action required)
    149 
    150   * ``Bank accounts``
    151 
    152   * ``Settings``
    153 
    154   * ``Logout``
    155 
    156 * ``Digital publishing`` showing:
    157 
    158   * ``Orders``, but exclude ``+``- button for creating new orders manually,
    159     that's already a power-user feature.
    160 
    161   * ``Subscriptions and Discounts`` (only after v1.6)
    162 
    163   * ``Access tokens``
    164 
    165   * ``KYC status`` (if action required)
    166 
    167   * ``Bank accounts``
    168 
    169   * ``Settings``
    170 
    171   * ``Logout``
    172 
    173 * ``E-commerce site`` showing:
    174 
    175   * ``Orders``, but exclude ``+``-button for creating new orders manually,
    176     that's already a power-user feature.
    177 
    178   * ``Subscriptions and Discounts`` (only after v1.6)
    179 
    180   * ``Webhooks``
    181 
    182   * ``Access tokens``
    183 
    184   * ``KYC status`` (if action required)
    185 
    186   * ``Bank accounts``
    187 
    188   * ``Settings``
    189 
    190   * ``Logout``
    191 
    192 
    193 Proposed Solution (Iteration 2)
    194 ===============================
    195 
    196 .. warning::
    197 
    198    The proposed simplifications here
    199    are still under discussion and will only
    200    be implemented once iteration 2 is done.
    201 
    202 
    203 Simplification of Resource Identifiers
    204 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    205 
    206 Currently, the user has to choose the resource identifier for templates,
    207 products, and so on. It's not clear to the typical user *why* they have to
    208 choose this, so we should provide a reasonable default for the resource ID.
    209 
    210 https://bugs.gnunet.org/view.php?id=10620
    211 
    212 
    213 Simplication of Bank Account Settings
    214 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    215 
    216 Currently we have three screens involving the bank account:
    217 ``Bank accounts`` (under configuration),
    218 ``KYC Status`` and ``Wire transfers``.
    219 
    220 Since all of the activities done on this screen are related to the bank
    221 account, we can simplify it into one ``Bank accounts`` page.
    222 
    223 .. note::
    224 
    225   When adding a bank account, we should only show the simplified
    226   dialog (IBAN, account owner information) and not the
    227   WireGateway part *unless* in "show everything" and/or "beta tester"
    228   mode. In terms of entering account owner information, we should
    229   allow entering more data, like ZIP code, City name, etc. as these
    230   are becoming more-and-more required. So not just "receiver-name".
    231   (But everything but receiver-name can be optional for now.)
    232 
    233 The wire transfers can be shown by clicking on the details page of a bank account.
    234 
    235 .. note::
    236 
    237   This feature needs more testing, I think we should only show
    238   it in ``Developer`` mode for now!
    239 
    240 The KYC status can also be shown in the table of the bank accounts.
    241 
    242 If KYC is required for a bank account, we can both highlight the bank account
    243 *and* also add a ``KYC required`` highlighted menu item that directly goes to
    244 the KYC status of a bank account that requires action.
    245 
    246 
    247 Screens (in improved version):
    248 
    249 * overview screen with list of bank accounts
    250 
    251   * Wire method (iban / x-taler-bank
    252   * Account ("<iban> · <name>" / "<account name> · <host>")
    253 
    254     * Host should not contain http(s)://
    255   * Owner's name
    256   * Readiness (show emoji, text on hover)
    257 
    258     * ✅ Ok
    259     * ⚠️ Action Required
    260     * ❌ Not working
    261   * "Wire transfers" button => takes use to wire transfers page, with account selected
    262   * "Edit" button
    263   * "Delete" button
    264 
    265 On click of a row with a bank account: Expand to show details
    266 
    267 Details of an expanded row:
    268 
    269 * list of exchanges that require an action
    270 * Button "Show all exchanges"
    271 
    272   * Pop ups a table with all exchanges, their status and limits
    273     
    274     * Grouped by "supported / "unavailable" exchanges for this account
    275       in collapsible sections, with the "unavailable" collapsed by default?
    276     * The "unavailable" section both has exchanges that are not reachable (network issues etc.)
    277       and ones that are incompatible w.r.t. currency or supported wire methods.
    278 
    279     * Columns for "supported":
    280 
    281       * Exchange URL
    282       * Status ("ok", "action required", "limit reached")
    283       * Limits (e.g. "Deposit: 50 CHF / month, 1500 CHF / year")
    284 
    285     * Columns for "unavailable":
    286     
    287       * Exchange URL
    288       * Reason ("currency mismatch", "wire method mismatch", "exchange is offline")
    289 
    290 
    291 -----
    292 
    293 Wire transfers page:
    294 
    295 Tab "Incoming":
    296 
    297 * Expected amount
    298 * Expected time
    299 * Exchange URL
    300 * Wire transfer ID (= expected subject?)
    301 * Button "Confirm"
    302 * If there's an error: Show "⚠️"-Element,
    303   when the row is clicked, it expands to show the error message
    304 
    305 Tab "Confirmed":
    306 * amount
    307 * time
    308 * Exchange URL
    309 * Wire transfer ID (= expected subject?)
    310 * Button "Undo confirmation"
    311 
    312 
    313 Simplication of OTP devices
    314 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    315 
    316 ``OTP devices`` are only used in combination with templates.  They are not
    317 used for logins etc., which might make it confusing to always show them.
    318 
    319 As a simplification, we could make the OTP devices *only* available via the
    320 ``Templates`` screen. So the ``Templates`` screen would basically have two
    321 tables (and ``+``-buttons), one for ``Templates`` and a second below
    322 for ``OTP devices``.
    323 
    324 
    325 Settings Structure
    326 ^^^^^^^^^^^^^^^^^^
    327 
    328 Currently we have:
    329 
    330 * ``Settings``: Contains five different types of settings:
    331 
    332   * payment-technical settings: transaction fee, payment delay default
    333   * contact information shown to the user
    334   * instance deletion
    335   * authentication-related settings (email / phone is used for auth)
    336 
    337 * Interface: Contains user interface settings.
    338 * Password: Change password
    339 
    340 We should also separate the phone number and email shown to the user and
    341 the one used for 2FA.
    342 
    343 Suggested restructuring:
    344 
    345 * ``Settings`` (with each sub-item as a collapsible section):
    346 
    347   * ``Personalization`` (was: Interface, only UI settings, *maybe* link to other settings)
    348 
    349   * ``Payment options``
    350 
    351     * default payment time
    352     * refund time
    353     * wire transfer time
    354     * auto-refund time (?)
    355     * STEFAN / payment fee options
    356 
    357   * ``Public profile`` (Contact settings as seen by the wallet users via contract terms)
    358 
    359     * We should add e-mail and phone number under the merchant ``address``
    360       in the contract terms (after all, they are contact addresses for the
    361       merchant). Many advantages, starting with no change required in the
    362       backend.
    363     * Jurisdiction => We need more info on how merchants use this in practice
    364 
    365   * ``Security`` (both password and 2FA-related fields)
    366 
    367     * Password
    368     * Phone number and e-mail address used for 2FA
    369     * Access tokens
    370 
    371       * Also show copyable base URL (#10657)
    372       * Later: QR code for PoS setup (#9791)
    373 
    374   * ``Integrations``
    375 
    376     * Webhooks
    377     * Future: Connected devices and services
    378 
    379       * For PoS access tokens
    380       * For turnstile, wordpress, etc.
    381 
    382   * ``About``
    383 
    384     * Version of UI
    385     * Version of merchant backend
    386     * backend base URL
    387 
    388 
    389 Sidebar Simplification
    390 ^^^^^^^^^^^^^^^^^^^^^^
    391 
    392 * Remove Wire transfers section (now redundant)
    393 * Remove KYC Status section (now redundant)
    394 * Remove OTP (now under Templates)
    395 * Remove Webhooks (now under settings)
    396 * Remove Passwords (now under settings)
    397 * Remove Access Tokens (now under settings)
    398 * Remove Personalization (now under settings)
    399 * Remove merchant backoffice domain (now under settings->about)
    400 * Move user login name at the top (instead of version)
    401 * Remove version number (now under settings->about)
    402 * Remove labels "Configuration" / "Connection"
    403 
    404 Definition of Done
    405 ==================
    406 
    407 TBD.
    408 
    409 Alternatives
    410 ============
    411 
    412 TBD.
    413 
    414 Drawbacks
    415 =========
    416 
    417 TBD.
    418 
    419 Discussion / Q&A
    420 ================
    421 
    422 * Can the persona be changed while being logged in?
    423 
    424   * Yes, under ``Personalization``, just like the language and date format.
    425 
    426 * Can the user choose a person at login or instance creation?
    427 
    428   * No, we want to avoid too many input fields / choices.
    429 
    430 * Is the chosen persona persistent?
    431 
    432   * Not for now, it's stored per local-storage.