DD 74: Merchant Backend Simplification

14.74. DD 74: Merchant Backend Simplification#

Status: incomplete draft

14.74.1. Summary#

This design document proposes simplifications to the merchant backend user interface.

14.74.2. Motivation#

The current merchant backend SPA provides a user interface tailored towards expert users that know the underlying protocol concepts.

14.74.3. Requirements#

  • The merchant backend SPA should be usable by non-experts

  • Different normal users will have different use-cases, requirements and background, so one-size-fits-all does not apply.

  • The merchant backend SPA should remain as a tool for expert users

  • We do not want to maintain different versions of the merchant backend SPA

14.74.4. Proposed Solution (Iteration 1)#

14.74.4.1. Existing Pages#

What follows is a listing of the menu entries in the merchant UI as of 2025-11-13. It serves as the basis of further discussion in this document.

Top-Level (unnamed)

  • Orders

  • Inventory

  • Categories

  • Wire transfers

  • Templates

  • KYC Status

Configuration:

  • Bank accounts

  • OTP Devices

  • Webhooks

  • Settings

  • Password

  • Access tokens

Connection:

  • Interface

Instances:

  • New

  • List

  • Logout

14.74.4.2. Personas#

  • Personas are a preset of feature flags and other settings

  • The backend provides a default persona. After login, the UI for this persona is chosen. It can be changed in the “Personalization” menu.

  • We do not call it “profiles”, because it clashes with the “profile” terminology as it is typically used in UIs (contact info, profile picture, …).

14.74.4.3. Persona Definitions#

  • Developer

    • Every feature flag on, developer mode on

    • Should come last in the drop-down

  • Expert

    • Every feature flag on, developer mode off

    • Second to last in dropdown

    • No Age restriction

    • No token families

  • Unattended in-person offline vending (minimal farm shop) showing:

    • Orders, but exclude +-button for creating new orders manually, that’s already a power-user feature.

    • Templates, but exclude OTP devices, only useful for power-users.

    • KYC status (but only if action required)

    • Bank accounts, including KYC status

    • Settings

    • Logout

  • Unattended in-person offline vending with inventory, (this choice should only be enabled once we have the next version of templates with inventory!) showing:

    • Orders, but exclude + button for creating new orders manually, that’s already a power-user feature.

    • Inventory (once supported by templates!)

    • Categories (once supported by templates!)

    • Templates, but exclude OTP devices, again, HW doesn’t exist yet,

      and only useful for power-users. Without age restriction and paymentTimeout option.

    • KYC status (if action required)

    • Bank accounts

    • Settings

    • Logout

  • In-person online point-of-sale with inventory showing:

    • Orders, but exclude +-button for creating new orders manually, that’s already a power-user feature.

    • Inventory

    • Categories

    • Access tokens

    • KYC status (if action required)

    • Bank accounts

    • Settings

    • Logout

  • Digital publishing showing:

    • Orders, but exclude +- button for creating new orders manually, that’s already a power-user feature.

    • Subscriptions and Discounts (only after v1.6)

    • Access tokens

    • KYC status (if action required)

    • Bank accounts

    • Settings

    • Logout

  • E-commerce site showing:

    • Orders, but exclude +-button for creating new orders manually, that’s already a power-user feature.

    • Subscriptions and Discounts (only after v1.6)

    • Webhooks

    • Access tokens

    • KYC status (if action required)

    • Bank accounts

    • Settings

    • Logout

14.74.5. Proposed Solution (Iteration 2)#

Warning

The proposed simplifications here are still under discussion and will only be implemented once iteration 2 is done.

14.74.5.1. Simplification of Resource Identifiers#

Currently, the user has to choose the resource identifier for templates, products, and so on. It’s not clear to the typical user why they have to choose this, so we should provide a reasonable default for the resource ID.

https://bugs.gnunet.org/view.php?id=10620

14.74.5.2. Simplication of Bank Account Settings#

Currently we have three screens involving the bank account: Bank accounts (under configuration), KYC Status and Wire transfers.

Since all of the activities done on this screen are related to the bank account, we can simplify it into one Bank accounts page.

Note

When adding a bank account, we should only show the simplified dialog (IBAN, account owner information) and not the WireGateway part unless in “show everything” and/or “developer” mode. In terms of entering account owner information, we should allow entering more data, like ZIP code, City name, etc. as these are becoming more-and-more required. So not just “receiver-name”. (But everything but receiver-name can be optional for now.)

The wire transfers can be shown by clicking on the details page of a bank account.

Note

This feature needs more testing, I think we should only show it in Developer mode for now!

The KYC status can also be shown in the table of the bank accounts.

If KYC is required for a bank account, we can both highlight the bank account and also add a KYC required highlighted menu item that directly goes to the KYC status of a bank account that requires action.

Screens (in improved version):

  • overview screen with list of bank accounts

  • Wire method (iban / x-taler-bank

  • Account (“<iban> · <name>” / “<account name> · <host>”) * Host should not contain http(s)://

  • Owner’s name

  • Readiness (show emoji, text on hover)

    • ✅ Ok

    • ⚠️ Action Required

    • ❌ Not working

  • “Wire transfers” button => takes use to wire transfers page, with account selected

  • “Edit” button

  • “Delete” button

On click of a row with a bank account: Expand to show details

Details of an expanded row: * list of exchanges that require an action * Button “Show all exchanges”

  • Pop ups a table with all exchanges, their status and limits

    • Grouped by “supported / “unavailable” exchanges for this account in collapsible sections, with the “unavailable” collapsed by default?

    • The “unavailable” section both has exchanges that are not reachable (network issues etc.) and ones that are incompatible w.r.t. currency or supported wire methods.

    • Columns for “supported”:

      • Exchange URL

      • Status (“ok”, “action required”, “limit reached”)

      • Limits (e.g. “Deposit: 50 CHF / month, 1500 CHF / year”)

    • Columns for “unavailable”:

      • Exchange URL

      • Reason (“currency mismatch”, “wire method mismatch”, “exchange is offline”)

Wire transfers page:

Tab “Incoming”:

  • Expected amount

  • Expected time

  • Exchange URL

  • Wire transfer ID (= expected subject?)

  • Button “Confirm”

  • If there’s an error: Show “⚠️”-Element, when the row is clicked, it expands to show the error message

Tab “Confirmed”: * amount * time * Exchange URL * Wire transfer ID (= expected subject?) * Button “Undo confirmation”

14.74.5.3. Simplication of OTP devices#

OTP devices are only used in combination with templates. They are not used for logins etc., which might make it confusing to always show them.

As a simplification, we could make the OTP devices only available via the Templates screen. So the Templates screen would basically have two tables (and +-buttons), one for Templates and a second below for OTP devices.

14.74.5.4. Settings Structure#

Currently we have:

  • Settings: Contains five different types of settings:

    • payment-technical settings: transaction fee, payment delay default

    • contact information shown to the user

    • instance deletion

    • authentication-related settings (email / phone is used for auth)

  • Interface: Contains user interface settings.

  • Password: Change password

We should also separate the phone number and email shown to the user and the one used for 2FA.

Suggested restructuring:

  • Settings (with each sub-item as a collapsible section):

    • Personalization (was: Interface, only UI settings, maybe link to other settings)

    • Payment options

      • default payment time

      • refund time

      • wire transfer time

      • auto-refund time (?)

      • STEFAN / payment fee options

    • Public profile (Contact settings as seen by the wallet users via contract terms)

      • We should add e-mail and phone number under the merchant address in the contract terms (after all, they are contact addresses for the merchant). Many advantages, starting with no change required in the backend.

      • Jurisdiction => We need more info on how merchants use this in practice

    • Security (both password and 2FA-related fields)

      • Password

      • Phone number and e-mail address used for 2FA

      • Access tokens

        • Also show copyable base URL (#10657)

        • Later: QR code for PoS setup (#9791)

    • Integrations

      • Webhooks

      • Future: Connected devices and services

        • For PoS access tokens

        • For turnstile, wordpress, etc.

    • OTP Devices (only for payment confirmation, not for login security!)

    • About

      • Version of UI

      • Version of merchant backend

      • backend base URL

14.74.6. Definition of Done#

TBD.

14.74.7. Alternatives#

TBD.

14.74.8. Drawbacks#

TBD.

14.74.9. Discussion / Q&A#

  • Can the persona be changed while being logged in?

    • Yes, under Personalization, just like the language and date format.

  • Can the user choose a person at login or instance creation?

    • No, we want to avoid too many input fields / choices.

  • Is the chosen persona persistent?

    • Not for now, it’s stored per session. We could make it persistent in the future, but there are no plans for that presently.

  • Should developer mode be a separate persona, or should there always be a developer mode toggle for every persona?

  • Problem with “developer as persona”: The developer mode already affects the behavior before login, such as when choosing a different backend base URL.