path: root/design-documents/053-wallet-ui.rst

DD 53: Wallet UI Design
#######################

Summary
=======

This document proposes designs wallet UI. It defines what Android, iOS and
WebExtension should follow in order to have a coherent UI between platforms.

Motivation
==========

We want user to be able to help each others independent of the implementation
they are using.
We want user to be able to capitalize the effort of learning how to use one
wallet and be able to use a different one without the need to learn
anything new.
Currently development of different platform specific implementation are independent
and every developer needs to choose the layout, texts and buttons and navigation.

Requirements
============

Every screen MUST be defined in a document with the following information:

* **Identifiable UI screens**: every UI should have an unique identifier that will
  be use for development discussion and bug reports. There should be an option
  in the application to enable an active rendering of the id.

* **Description**: the reason to be of the screen, should help to define what will
  be included into, what is going to left for other screens and when and from
  where should be linked.

The screen MAY also have:

* **Predefined assets**: every implementation should resue the same icons, images,
  fonts and sounds.

Additionaly the document COULD defined the components of the UI. If one of this
properties is defined in the spec the implementation must implement it. The specification
should be minimal to achieve the objective in the description.

* **Info**. Spec of information that the user should have access. The type of info
  could be a field (id and value) or a banner (information and instructions).
  The spec will help to reuse the text for i18n across apps and defined

* **Inputs**. Spec of information need to provide in current screen. The type of input,
  range of values and validation should be defined if necessary.

* **Actions**. Spec of buttons and interactable elements that will have a significant
  change in the current state. It should also mention navigation when applicable.

* **Layout**. Spec position of elements when needed. The spec should be "soft" in a sense
  that elements should be easy to find following directions like "close to X" or
  "at the start/end of the screen".

* **Issues**. Issues we identified that need to be addressed in some implementation(s).
  This is in particular about inconsistencies and bad design choices made on some
  platforms.

* **Adoption**. Things that one version does particularly
  nice that we might want other implementations to adopt.

* **Screenshots**. Should be provided for all wallet implementations and kept
  up to date, to ensure that they can be used to aid in UI/UX and QA
  discussions.

Screen should be defined using the most relaxed definition that are good enough to
be clear for the user. Platform will use this definition and adapt to the differences
on the platform taking advantange of platform API and screen sizes.

When a screen have multiple uses for the same purpose, a substate section should be
included with the difference with the main definition.

Part of the screens that are reused shoud also be defined in this document as screen.

Common definition:
 * navigation between screens should not happen if the user didn't take any action


Proposed Solutions
==================

List of all screens with the defined properties.

.. _cta-balance-list-ref:

balance-list
------------

This screen shows a currency-scoped list of the balances stored in the wallet,
and includes information about the total, incoming, and outgoing amounts, as
well as the currency scope information for each item.

Info
^^^^

* List of balances in the wallet, where each item contains:

  * Total amount with currency (see :doc:`051-fractional-digits`).
  * Incoming amount (money pending to arrive).
  * Outgoing amount (money pending to leave).
  * Currency scope information (see :doc:`035-regional-currencies`).

* Strings to use:

  * Title is "Balances"
  * "inbound" and "outbound" are used with
    pending amounts (shown if applicable below the main
    amount, green for inbound, red for outbound)
  * "pending" MAY be used as a badge label to indicate
    that there are pending activities

Layout
^^^^^^

* There SHOULD be a menu or button from where the QR code entry / scan
  functionality is reachable (:ref:`cta-url-entry-ref`)
* There SHOULD be a menu or button from where the settings screen (:ref:`cta-settings-ref`)
  is reachable, unless settings are handled differently
  on the platform.
* In developer mode, there MAY be a menu or button
  from where the developer tools (:ref:`cta-devtools-ref`)
  are reachable. Alternatively, developer tools COULD
  also only be reachable via settings.


Issues
^^^^^^

* WebEx (minor): Inconsistent to aldready have
  the "add" and "send" buttons on this page.
* WebEx (image): Screenshot does not show any
  pending transactions.
* Android (text): Uses "Exchange:" which is
  not user-facing terminology. Should only show the URLs.
* Android (minor): Screenshot shows only a "pending"
  badge, which seems redundant given "+10 KUDOS inbound"
  (too much information?)
* iOS (major): Way too much detail shown, way too
  much explanation text, too many operations
  (send money, request payment, spend test money!!!!);
  Remove text "Balance:" within each currency, this
  is all about *Balances* as per the title. Instead,
  show the balance right of the currency name.
* iOS (major): overly complex menu with balances and
  banking; we are NOT a banking app, banking is IMO
  confusing. Settings icon could be on top left, then
  it would be more uniform, I would get rid of banking
  'tab' entirely!
* iOS (text): bad icon for "pending outgoing", the
  "minus" sign does not give me good associations here
* Android (text): Title should be *Balances* (plural)
* Android (minor): No "add" and "Send $CURRENCY" buttons
  on this page.



Adoption
^^^^^^^^

* iOS: transaction history visualization with red/green
  bars after currency is nice.


Actions
^^^^^^^

* **View transactions**. Clicking on a balance item should take you to the
  transaction list (:ref:`cta-transaction-list-ref`) associated with that balance.

Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------------+
| Platform  | Screenshot                                                             |
+===========+========================================================================+
| WebEx     | .. image:: ../screenshots/cta-balance-list-firefox-latest.png          |
+-----------+------------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-balance-list-android-latest.png          |
|           |    :width: 30%                                                         |
+-----------+------------------------------------------------------------------------+
| iOS       | .. image:: wallet-screenshots/ios-wallet/11-balances-list-latest.png   |
|           |    :width: 30%                                                         |
+-----------+------------------------------------------------------------------------+


.. _cta-transaction-list-ref:

transaction-list
----------------

This screen shows a list of all the transactions associated with a given
currency scope.

Info
^^^^

* Total amount and currency (see :doc:`051-fractional-digits`).
* List of transactions associated with the currency scope, with pending
  transactions on top, and where each item contains the following:

  * **Title**. It depends on the transaction type. It can be the exchange URL
    (e.g. exchange.demo.taler.net) for withdraw,
    the receiver name from the payto-URI for
    deposits,
    the human-provided summary of the transaction
    (for push- and pull- P2P payments),
    the name of the merchant paid
    (e.g. Essay Shop) for payments to merchants and
    refunds
  * **Status**. It provides complementary information about the transaction
    for the user, such as the status of the transaction (e.g. “Waiting for
    confirmation,” “KYC required,” an error message, etc.). (The summary is
    provided by wallet-core, along with internationalized versions.)
  * **Timestamp**. The moment when the transaction was created. Ideally, it
    should be shown with minimal precision, only showing the minutes, hours or
    days that have elapsed.
  * **Amount**. The positive or negative impact that the transaction has in
    the total balance of the currency scope. It should be made clear whether
    the amount of the transaction is positive or negative, ideally with a sign
    (+/-) and a color (green/red).
  * **Pending**. It should be indicated whether the transaction is pending or
    finished. This can be done with a small badge and with different colors,
    however, it should be always clear and communicate the message
    effectively.

Actions
^^^^^^^

* **Send**. The transaction list should include a button that allows the user
  to initiate transactions that result in money being sent, such as deposits
  and peer push payments.
* **Receive**. The transaction list should also include a button that allows
  the user to initiate transactions that result in money being received, such
  as withdrawals and peer pull payments.
* **View transaction details**. When clicking on a transaction, the user
  should be taken to its corresponding transaction details depending on the
  type of the transaction clicked.
* **Select transaction(s)**. The user should be able to select one or more
  transactions to perform specific bulk actions, such as deleting. The
  interaction that triggers this action might differ across platforms. For
  example, in Android this would be achieved by double pressing a transaction
  (to activate selection mode) and then clicking other transactions to be
  selected. On iOS, this could be achieved using an “Edit” button in the
  toolbar that reveals checkboxes that allow the user to select the desired
  transactions.
* **Delete transaction(s)**. This could be achieved in bulk via selection
  mode, or individually for each transaction via a menu or a button. Either
  way, performing a deletion should always show a confirmation menu before
  doing the actual deletion.

Layout
^^^^^^

* The specific currency for which transactions are shown
  SHOULD be prominent (title bar, menu bar)
* The current balance should be on top (ideally always on-top)
  just below the title and on the right of the "send" and "receive"
  buttons. The current balance should align with the amounts
  of the various transactions below.  If possible, it should
  have a label "Balance" near (ideally above) it.
* There needs to be a way to go "back" to the
  balance list (:ref:`cta-balance-list-ref`) **if**
  we have more than a single currency in use. This
  can be some (optional) "back" button or some
  "home" button or some "balances" menu entry.
* There should be a menu or button from where the QR code entry / scan
  functionality is reachable (:ref:`cta-url-entry-ref`)
* There COULD be a menu or button from where the settings screen (:ref:`cta-settings-ref`)
  is reachable. The settings screen MUST be reachable
  **if** there is no way to get to the balance list screen
  because we only have a single currency.
* In developer mode, there MAY be a menu or button
  from where the developer tools (:ref:`cta-devtools-ref`)
  are reachable. Alternatively, developer tools COULD
  also only be reachable via settings.


Issues
^^^^^^

* WebEx (text): Iconography (T), (W) is not as
  nice as iconography in on Android.
* WebEx (text): The balance is not labeled as the balance.
* WebEx (text): Button is labeled as "Add",
  while above says to use "Receive" which is
  a better dual with "Send".
* WebEx (image): Screenshot does not show any
  pending transactions.
* WebEx (nit): Android has different order of
  items on top (send+receive, then balance).
  This places the balance on top of the other
  amounts, which is nicer.
* Android (text): Iconography (same icon for push
  payments and debit and POS) and again same icon
  for invoice and withdraw) is sub-optimal. Should
  pick unique icons for each type of operation.
* Android (text): Button labels should just be
  "Send" and "Receive" (without "funds").
* iOS (text): Iconography (+ / -) is also not
  expressive and redundant with the colors.
* iOS (text): Sign of the operation (+ / -) should
  be just before the amount (see Android), not
  all the way on the left as an icon. Also can
  probably be more subtle?
* iOS (text): currency symbol in front of every
  amount value is highly redundant; would be better
  to list the currency once in the title (see Android)
* iOS (minor): lacks search button (see Android)
* all (text): use the merchant name for the main
  transaction label on refunds (and payments to
  merchants)
* all (text): Use the human-provided *summary* of the
  P2P payment for both push and pull payments (the
  direction is clear from +/- on the amount, and
  it should not matter who initiated!)
* all (text): "Deposits" should use the receiver name
  of the payto-URI of the target account (URL-decoded)
  in the main title, instead of "Deposit"
* iOS (text): "Withdrawal" shown instead of
  exchange URL for withdraw
* iOS (text): "Sent Requested money" shown instead of
  exchange URL for withdraw
* iOS (major): The balance is not shown. The
  "send" and "receive" buttons are missing.
* WebEx (minor): lacks search button (see Android)
* iOS (minor): has top/buttom scroll buttons not present
  in other UIs (likely too much, better to have search!)
* WebEx (minor): unclear how to do bulk-deletion;
  other platforms make it easy to select multiple
  rows. Maybe have some checkboxes and then a
  "delete selected" button at the bottom?
* iOS (critical): the buttons to send/receive funds
  are not even shown in the screenshot, likely because
  of balances vs. banking distinction, which should
  also be removed.
* All (critical): we do not seem to have
  screenshots of what happens after picking
  select funds or receive funds!


Adoption
^^^^^^^^



Screenshots
^^^^^^^^^^^

+-----------+--------------------------------------------------------------------+
| Platform  | Screenshot                                                         |
+===========+====================================================================+
| WebEx     | .. image:: ../screenshots/cta-transaction-list-firefox-latest.png  |
+-----------+--------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-transaction-list-android-latest.png  |
|           |    :width: 30%                                                     |
+-----------+--------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-transaction-list-ios-latest.png      |
|           |    :width: 30%                                                     |
+-----------+--------------------------------------------------------------------+


.. _cta-withdraw-review-ref:

cta-withdraw-review
-------------------

This screen is used to inform the user that before they can proceed
with a withdrawal, they must accept the terms of service of the exchange.


Info
^^^^

* service provider to be used showing the URL
* amount to be withdrawn
* applicable fees (if any)

* Text:

  * Use "payment service provider" to label the
    URL, not "exchange"
  * Use "Net" and "Fees" and "Gross" to label
    the amount in a section "Details"

Inputs
^^^^^^

* service provider: allow the selection of different exchange (if applicable)


Actions
^^^^^^^

* **change service provider**: updates fees shown (after returning from exchange selection screen)
* **review and confirm ToS**: advance to the :ref:`cta-accept-tos-ref` screen
* **back**: user will be redirected to previous screen

.. attention::
  User should be able to play with the amount, not possible in the current design

Issues
^^^^^^

* All(critical): This is an extremely lazy screen,
  and it probably should be completely revamped.
  We should allow the user to change the exchange
  **and** to enter the amount to withdraw
  **unless** a fixed amount (or exchange) were
  given when we were triggered.
  Editing the exchange should go to another screen
  (for now, with a simple URL entry bar, in the
  future with exchange comparisson and whatever);
  the fees should already be shown on this screen
  for the selected exchange.
* All(critical): We should probably unify this screen
  with cta-withdraw-confirm and cta-withdraw,
  with the only difference
  being that one variant has "View Terms of Service"
  while the other has a "Withdraw $AMOUNT" button.
* iOS(image): no screenshot available
* All(text): Use "Net" and "Fees" and "Gross" to label
  the amounts in a section "Details"


Screenshots
^^^^^^^^^^^

+-----------+-----------------------------------------------------------------+
| Platform  | Screenshot                                                      |
+===========+=================================================================+
| WebEx     | .. image:: ../screenshots/cta-withdraw-review-chrome-latest.png |
+-----------+-----------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-withdraw-review-android-latest.png|
|           |    :width: 30%                                                  |
+-----------+-----------------------------------------------------------------+




.. _cta-withdraw-ref:

cta-withdraw
------------

This screen is used for the confirmation of a manual withdrawal,
bank-integrated witdrawals and exchange withdrawals.  the success of this
operation will be an increase of the balance in the wallet.  fee, restrictions
and ETA should be clear for the user.

Info
^^^^

* exchange to be used showing the URL
* table of details of the operation: use the :ref:`operation-table-details-ref` screen
* starting currency: if the exchange has the currency conversion service enabled user should be able to the details based on the wire transfer currency
* taler URI: show copy button or QR to complete the operation with another device

Inputs
^^^^^^

* age restriction: allow the selection of the restriction in the age group possible by the exchange
* service provider: allow the selection of different exchange

Actions
^^^^^^^

* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
* **review and confirm ToS**: if the current selected exchange has a version  of ToS that the user didn't yet accepted, use the :ref:`cta-accept-tos-ref` screen
* **cancel**: user will be redirected to ``balance``

.. attention::
  User should be able to play with the amount, not possible in the current design

Issues
^^^^^^

* All(screenshots): the flow here diverges completely betwen the different platforms (very bad).
* Android(major): there really should not be a "check fees" button here, the fees should just be dynamically calculated and shown immediately. Note that the dialog shown here is thus closer to what we might make the future main
  withdraw review (:ref:`cta-withdraw-review-ref`) dialog.


Adoption
^^^^^^^^

* We should probably keep the "specify the origin
  of the money" from Firefox as a dialog after
  "Receive funds" is selected in the
  transaction list (:ref:`cta-transaction-list-ref`),
  but without the amount entry. Keep it simple,
  mostly binary choice: withdraw, invoice, or back.
* The iOS dialog is reasonably close to the future
  withdraw review (:ref:`cta-withdraw-review-ref`) dialog,
  allowing amount entry, shows fees, and final "confirm"
  button (I guess: "review ToS" should be an alternative
  button label). Eventually, we'll want an "edit" (pen)
  icon next to the exchange URL, and
  if context has fixed the amount or exchange, the
  respective buttons should be hidden.


Screenshots
^^^^^^^^^^^

+-----------+----------------------------------------------------------------+
| Platform  | Screenshot                                                     |
+===========+================================================================+
| WebEx     | .. image:: ../screenshots/cta-withdraw-firefox-latest.png      |
+-----------+----------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-withdraw-android-latest.png      |
|           |    :width: 30%                                                 |
+-----------+----------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-withdraw-ios-latest.png          |
|           |    :width: 30%                                                 |
+-----------+----------------------------------------------------------------+


.. _cta-withdraw-confirm-ref:

cta-withdraw-confirm
--------------------

This screen is used to ask the the user to confirm the withdrawal operation,
now that all data has been provided.


Info
^^^^

* service provider to be used showing the URL
* amount to be withdrawn
* applicable fees (if any)

Inputs
^^^^^^

* none?


Actions
^^^^^^^

* **confirm withdraw**: advances to next screen
* **back**: user will be redirected to previous screen

Issues
^^^^^^

* All: This dialog should be merged with
  the future main
  withdraw review (:ref:`cta-withdraw-review-ref`) dialog
  where the amount and exchange could be edited (if
  permitted by trigger event) and the fees are dynamically
  shown. No point in yet another dialog.


Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-withdraw-confirm-firefox-latest.png|
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-withdraw-confirm-android-latest.png|
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+




.. _cta-wire-transfer-ref:

cta-wire-transfer
-----------------

This screen is used to show the user the information for the wire transfer to
complete a manual withdrawal operation.

Info
^^^^

* wire transfer subject to be used (first, most important)
* target bank account to transfer funds to (e.g. IBAN)
* total amount to transfer in the wire transfer currency
* button to copy ``payto://`` URI with the information to clipboard

Actions
^^^^^^^

* **abort**: aborts the withdrawal operation
* **menu**: go back to the main balances list (operation continues in background)
* **automatic**: screen changes to "cta-withdraw-done" upon completion

Issues
^^^^^^

* WebEx(text): wire transfer subject is last, should be first!
* WebEx(text): Receiver name is not shown (except within payto URI); must be shown above IBAN!
  and only a link shown (see iOS)
* WebEx(text): PaytoURI should not be expanded on-screen
  and only a link shown (see iOS)
* All(text): if there is no fee, no point in showing
  the amount **3** times. Maybe only show the amount
  on top with the wire transfer details, and then at
  the bottom show the fee ONCE *if* there is one?
* Android(text): uses "exchange", which is verboten
* iOS(text): receiver name is missing, MUST be before IBAN
* Android(text): wire transfer subject is third, should be first
* WebEx(screenshot): the screenshot does not show how to select an alternative bank (see: Netzbon). Would be nice to show that.
* Android(screenshot): the screenshot does not show how to select an alternative bank (see: Netzbon). Would be nice to show that.



Adoption
^^^^^^^^

* WebEx/Android(text): Probably best to take the full text of the 3 steps from iOS (but add receiver name in step 2!) to provide very precise instructions.
* WebEx/Android(text): "Open in banking app" is likely unclear that this requires Payto://-support. Use the long text from iOS everywhere!
* iOS(minor): the way to switch between different banks is not as clear as it was on WebEx. Proposal: use notebook tabs similar to how it is done on WebEx (IIRC?)
* Android: transaction status is not shown ("pending" on all other platforms. This is actually *good*, as once we are no longer "pending" the wire transfer details will no longer be shown, so the entire screen will look different. So we can probably get rid of the "This transaction is not complete" and "Status: Pending" on WebEx/iOS as that is *always* the case when we give the user wire transfer instructions here!



Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-wire-transfer-firefox-latest.png   |
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-wire-transfer-android-latest.png   |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-wire-transfer-ios-latest.png       |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+


.. _cta-withdraw-done-ref:

cta-withdraw-done
-----------------

This screen is used to show the user the information for a completed withdraw
operation (bank-integrated or manual).

Info
^^^^

* amount wired  (hidden if no fees)
* fees paid (hidden if no fees)
* total amount withdrawn into wallet (effective balance change)
* exchange base URL
* date

Actions
^^^^^^^

* **delete**: deletes information about the withdrawal operation

Issues
^^^^^^

* WebEx(text): not point in showing details if there are no fees.
* iOS(text): not point in showing details if there are no fees.
* Android(text): still talks about 'exchange'
* Android(text): has the amount twice, useless without fees
* iOS(text): status: Done is unnecessary, if we show this screen, it will always be 'done' (ok, theoretically in the middle of withdrawing, but the wire transfer will be done; but then maybe show 'incoming' but hide the status once really "done").
* unclear: "Delete" vs. 'Delete from history" --- two
  styles, two translations, gain?


Adoption
^^^^^^^^

* We probably want to show a "pending" transaction if we
  are still withdrawing (wire transfer did arrived, coins
  are still being generated). That's a very brief time,
  but we probably want to use a minor variation of this
  dialog in that case.  Not sure it needs to be quite
  as prominent as on iOS though...



Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-withdraw-done-firefox-latest.png   |
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-withdraw-done-android-latest.png   |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-withdraw-done-ios-latest.png       |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+


.. _cta-url-entry-ref:

cta-url-entry
-------------

This screen allows the user to scan a QR code, scan an NFC tag, or enter a
taler://-URL.  Its implementation may differ significantly between
platforms. For example, scanning NFC tags may be fully automated, scanning QR
codes may involve some system applications, and maybe the dialog only allows
the URL entry *or* the camera but not both at the same time, depending on
implementation specifics.

Info
^^^^

* camera with current image to enable user to focus on QR code
* current URL, with information if it is not well-formed for GNU Taler
* possibly status information on NFC reader (if available)

Actions
^^^^^^^

* **open**: if entered manually, open URL as-entered (otherwise open is automatic)
* **back**: return to previous view

Issues
^^^^^^

* WebEx(text) has additional actions "clear" (not necessary, I can manually clear), "Read QR from file" (who does that!???!) that should be removed.
* Android(text) has button label "OK", should probably be "Open" for uniformity.
* Android(text) has "Enter Taler URI", while WebEx has clearer text "enter taler:// URI".
* iOS (screenshot): lacks dialog (or screenshot?) entirely, not sure if we need manual URL-entry on mobile though, so could be OK!




Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-url-entry-firefox-latest.png       |
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-url-entry-android-latest.png       |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+


.. _cta-payment-ref:

cta-payment
-----------

This screen is used for the confirmation of a payment to a merchant.  the
success of this operation will be an decrease of the balance in the wallet and
save a ticket/invoice of the purchase.  fee, restrictions and ETA should be
clear for the user.

Info
^^^^

* merchant offering the order showing the URL
* order summary
* table of details of the operation: use the :ref:`operation-table-details-ref` screen
* receipt: order id
* payment deadline: absolute time before the claimed order expires
* taler URI: show copy button or QR to complete the operation with another device
* cant pay desc: if the user has enough balance but unable to use it
* payment status: if the

Actions
^^^^^^^

* **confirm operation**: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
* **get more cash**: if there is not enough balance, it will be redirected to :ref:`cta-withdraw-ref`
* **cancel**: user will be redirected to ``balance``

Issues
^^^^^^

* WebEx(Text): showing price/total without fees is a bit excessive, could be simplified in absence of fees
* WebEx(Text): "Valid until" is likely confusing, not shown on other platforms. Maybe only show "offer expired" instead of pay button (on all platforms!)?
* WebEx(Text): Receipt number is not shown on other platforms at this time, which also makes sense as it is only an order number and certainly nothing like a receipt before payment! (Remove!)
* WebEx(Screenshot): would be good to show the dialog with expanded order details as well, maybe even expand by default like on Android (and forgo the button?)
* WebEx(Screenshot): would be good to show a version of the dialog with fees in the screenshot.
* iOS(text): the label 'Summary' appears only on iOS, and seems unnecessary. Especially since no long-form is available anywhere.
* All(screenshot): would be good to have sceenshots of the main variations: with/without product preview images, with/without fees, full details/partial details (if we have such a toggle).


Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-payment-firefox-latest.png         |
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-payment-android-latest.png         |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-payment-ios-latest.png             |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+


.. _cta-payment-paid-ref:

cta-payment-paid
----------------

This screen is used to show information with details about a historic payment.

Info
^^^^

* merchant offering the order showing the URL
* order summary
* table of details of the operation: use the :ref:`operation-table-details-ref` screen
* receipt: order id
* payment status: if the order was refunded
* Text to use:

  * **Title**. Name of the merchant paid
    (e.g. Essay Shop)
  * **Status**. It provides complementary information about the transaction
    for the user, such as the status of the transaction (e.g. “Waiting for
    confirmation,” “KYC required,” an error message, etc.). (The summary is
    provided by wallet-core, along with internationalized versions.)
  * **Timestamp**. The moment when the payment was made. Ideally, it
    should be shown with minimal precision, only showing the minutes, hours or
    days that have elapsed.
  * **Amount**. The negative impact that the transaction has in
    the total balance of the currency scope. It should be made clear that the amount is negative, ideally with a sign (-) and a color (red).


Actions
^^^^^^^

* **delete**: delete information about the transaction
* **back**: user will be redirected to ``balance``

Issues
^^^^^^

* WebEx(text): Details should be simplified if there are no fees
* Android(text): details say receipt, but WebEx uses the slightly more accurate "Invoice ID". Could also use "Order #"?
* iOS(major): delete button is missing, instead only has "Done"



Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-payment-paid-firefox-latest.png    |
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-payment-paid-android-latest.png    |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-payment-paid-ios-latest.png        |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+


.. _cta-deposit-ref:

cta-deposit
------------

This screen is used for the confirmation of a deposit.  the success of this
operation will be an decrease of the balance in the wallet and save a deposit
ticket for reference.  fee, restrictions and ETA should be clear for the user.

Info
^^^^

* bank account where the money is going to
* table of details of the operation: use the :ref:`operation-table-details-ref` screen

Actions
^^^^^^^

* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
* **cancel**: user will be redirected to ``balance``

.. attention::
  User should be able to play with the amount, not possible in the current design

Issues
^^^^^^

* WebEx(screenshot): need new section in this document for 'ctx-manage-account'.
* WebEx(minor): should probably separate out target account selection and amount entry, as done on iOS
* WebEx(text): "amount" is a bad label, "brut amount" might be good, then use "net deposit"
* WebEx(text): might be good to have "net deposit" amount also editable, not just computed (and then update "brut amount").
* Android(screenshot): lacks screenshots for dialogs where we enter/edit accounts and amounts
* Android(minor): if we do it iOS/WebEx style, we can probalby skip the 'pure' confirmation dialog and have the one where the brut/net amounts are entered be the final one in the sequence before the transaction happens
* all(screenshot): we need a new dialog showing the transaction in-flight/done as reachable via transaction history


Adoption
^^^^^^^^

* iOS: I think it makes sense to split this section up into account selection / management and amount entry & confirmation; we should only have one major screen per section! Please split other UIs similarly and let's introduce a new section here.





Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-deposit-firefox-latest.png         |
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-deposit-android-latest.png         |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-deposit-1-ios-latest.png           |
|           |    :width: 30%                                                   |
|           | .. image:: ../screenshots/cta-deposit-2-ios-latest.png           |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+


.. _cta-peer-pull-initiate-ref:

cta-peer-pull-initiate
----------------------

This screen is used for the confirmation of the creation of a peer pull
transaction or invoice to request money from another wallet.  the success of
this operation will not change the balance immediately in the wallet and allow
the user to share a taler URI to the payer.  fee, restrictions and ETA should
be clear for the user.

Info
^^^^

* exchange to be used showing the URL
* table of details of the operation: use the :ref:`operation-table-details-ref` screen

Inputs
^^^^^^

* **subject**: short description of the transaction
* **expiration**: absolute time/date after which the invoice is not valid anymore
* **service provider**: allow the selection of different exchange

Actions
^^^^^^^

* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
* **review and confirm ToS**: if the current selected exchange has a version  of ToS that the user didn't yet accepted, use the :ref:`cta-accept-tos-ref` screen
* *cancel*: user will be redirected to ``balance``

.. attention::
  Is the invoice creation always free of charge or does the exchange have a mechanism
  to impose a fee to pay on creation?

Issues
^^^^^^

* WebEx(text): 20 days is odd, Android has 30 days instead
* Android(text): Webex uses "1 Week" instead of "7 days", let's use "week".
* iOS(text): 3 min/ 1h are inconsistent; other wallets have 1 day, 7 days, 30 days. We should be consistent.


Adoption
^^^^^^^^

Screenshots
^^^^^^^^^^^

+-----------+----------------------------------------------------------------------+
| Platform  | Screenshot                                                           |
+===========+======================================================================+
| WebEx     | .. image:: ../screenshots/cta-peer-pull-initiate-firefox-latest.png  |
+-----------+----------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-peer-pull-initiate-android-latest.png  |
|           |    :width: 30%                                                       |
+-----------+----------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-peer-pull-initiate-ios-latest.png      |
|           |    :width: 30%                                                       |
+-----------+----------------------------------------------------------------------+


.. _cta-peer-pull-confirm-ref:

cta-peer-pull-confirm
---------------------

This screen is used for the confirmation of the payment of a peer pull
transaction or invoice to send money from another wallet.  the success of this
operation will be an will decrease the balance in the wallet.  fee,
restrictions and ETA should be clear for the user.

Info
^^^^

* exchange to be used showing the URL
* subject: short description of the transaction
* table of details of the operation: use the :ref:`operation-table-details-ref` screen
* expiration: absolute time/date after which the invoice is not valid anymore

Actions
^^^^^^^

* **confirm operation**: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
* **get more cash**: if there is not enough balance, it will be redirected to :ref:`cta-withdraw-ref`
* **cancel**: user will be redirected to ``balance``

cta-peer-push-initiate
----------------------

This screen is used for the confirmation of the creation of a peer push
transaction or transfer money to another wallet.  the success of this
operation will reduce the balance immediately in the wallet and allow the user
to share a taler URI to the receiver.  fee, restrictions and ETA should be
clear for the user.

Info
^^^^

* table of details of the operation: use the ``operation-table-details`` screen

Inputs
^^^^^^

* **subject**: short description of the transaction
* **expiration**: absolute time/date after which the transfer is not valid anymore

Actions
^^^^^^^

* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
* **cancel**: user will be redirected to ``balance``

Issues
^^^^^^

* WebEx(minor): forces user to scroll to the bottom. Android nicely shows the accept button always; that seems nicer;
* WebEx(text): has text about "Digital cash withdrawal" above. Would be more consistent if we also *only* showed the Terms of service.
* Android(text): uses "Exchange", should say "PSP's Terms of Service"
* iOS(screenshot): lacks actual ToS, not ideal to compare!


Adoption
^^^^^^^^


Screenshots
^^^^^^^^^^^

+-----------+----------------------------------------------------------------------+
| Platform  | Screenshot                                                           |
+===========+======================================================================+
| WebEx     | .. image:: ../screenshots/cta-peer-push-initiate-firefox-latest.png  |
+-----------+----------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-peer-push-initiate-android-latest.png  |
|           |    :width: 30%                                                       |
+-----------+----------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-peer-push-initiate-ios-latest.png      |
|           |    :width: 30%                                                       |
+-----------+----------------------------------------------------------------------+


.. _cta-peer-push-confirm-ref:

cta-peer-push-confirm
---------------------

This screen is used for the confirmation of the acceptance of a peer push
transaction or transfer money to this wallet.  the success of this operation
will be an will decrease the balance in the wallet.  fee, restrictions and ETA
should be clear for the user.

Info
^^^^

* subject: short description of the payment
* expiration: absolute time/date after which the invoice is not valid anymore
* table of details of the operation: use the ``operation-table-details`` screen

Actions
^^^^^^^

* **confirm operation**: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
* **review and confirm ToS**: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the :ref:`cta-accept-tos-ref` screen
* **cancel**: user will be redirected to ``balance``

Issues
^^^^^^

* All(screenshot): we have no screenshots!


Adoption
^^^^^^^^


Screenshots
^^^^^^^^^^^


.. _operation-table-details-ref:

operation-table-details
-----------------------

With the table it should be clear how much the operation will cost, the
initial amount and the final amount with all the items related to the
operations (like fee)

Labels
^^^^^^

Initial amount of the operation, and final amount are always shown. Fee should
be shown as an extra row in the table if it is non-zero. Converted amount
should be shown as an extra row if initial amount currency is not the same as
the final amount currency.

Initial amount label by operation:

 * payment -> Price
 * deposit -> Send
 * peer-pull-credit -> Invoice
 * peer-pull-debit -> Invoice
 * peer-push-debit -> Send
 * peer-push-credit -> Transfer
 * withdrawal -> Transfer
 * refund -> Refund


.. _cta-accept-tos-ref:

accept-tos
----------

This screen can be use everytime that the user is going to interact with an
exchange. since at any moment wallet may find that ToS changed the user needs
to be prevented from continue before reading/accepting new rules. If possible,
this screen should be used inplace of other actions and hidden if not required
(for example, user already accepted ToS)

Inputs
^^^^^^

* **format**: allow the selection of a ToS format
* **languange**: allow the selection of a languange different from system lang

Actions
^^^^^^^

* **accept tos**: will mark this version as accepted in wallet core and redirect the user to the screen from where it was invoked
* **save/print tos**: will save the ToS outside of the wallet

Issues
^^^^^^



Adoption
^^^^^^^^


Screenshots
^^^^^^^^^^^

+-----------+------------------------------------------------------------------+
| Platform  | Screenshot                                                       |
+===========+==================================================================+
| WebEx     | .. image:: ../screenshots/cta-accept-tos-firefox-latest.png      |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+
| Android   | .. image:: ../screenshots/cta-accept-tos-android-latest.png      |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+
| iOS       | .. image:: ../screenshots/cta-accept-tos-ios-latest.png          |
|           |    :width: 30%                                                   |
+-----------+------------------------------------------------------------------+

.. _cta-settings-ref:

settings
--------

Info
^^^^

Layout
^^^^^^

Actions
^^^^^^^

Issues
^^^^^^

Adoption
^^^^^^^^

Screenshots
^^^^^^^^^^^


.. _cta-devtools-ref:

developer-tools
---------------

Info
^^^^

Layout
^^^^^^

Actions
^^^^^^^

Issues
^^^^^^

Adoption
^^^^^^^^

Screenshots
^^^^^^^^^^^





Q / A
=====