004-wallet-withdrawal-flow.rst (5563B)
1 DD 04: Wallet Withdrawal Flow 2 ############################# 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Torsten Grote 8 :First published: 2020-04-23 9 :Last substantive change: 2020-07-20 10 :Implementation evidence: taler-typescript-core (2022-08-26) 11 :Normative references: :doc:`048-wallet-exchange-lifecycle`, :doc:`../wallet/wallet-core` 12 13 Summary 14 ======= 15 16 This document describes the recommended way of implementing the user experience 17 of withdrawing digital cash in GNU Taler wallets. 18 19 Motivation 20 ========== 21 22 When digital cash is withdrawn, it is tied to and in custody of an exchange. 23 There can be many exchanges offered by different entities, 24 each having their custom legal agreement documents and fee structures. 25 The user is free to choose an exchange. 26 Therefore, the process of withdrawing needs to account for this choice. 27 28 Proposed Solution 29 ================= 30 31 There are three screens involved in the process: 32 33 1. **Select exchange**: 34 Here the user can pick an exchange from a list of known exchanges 35 or add a new one for immediate use. 36 For the current lifecycle and selection model see 37 :doc:`048-wallet-exchange-lifecycle`. 38 2. **Display an exchange's Terms of Service**: 39 Shows the terms and gives an option to accept them. 40 For details see :doc:`003-tos-rendering`. 41 3. **Withdrawal details and confirmation**: 42 This should show the amount to be withdrawn along with its currency, 43 the currently selected exchange and the fee charged by it for the withdrawal. 44 45 The user flow between these screens is described in the following graph: 46 47 .. graphviz:: 48 49 digraph G { 50 rankdir=LR; 51 nodesep=0.5; 52 default_exchange [ 53 label = "Has default\nexchange?"; 54 shape = diamond; 55 ]; 56 tos_changed [ 57 label = "ToS\nchanged?"; 58 shape = diamond; 59 ]; 60 tos_accepted [ 61 label = "ToS\naccepted?"; 62 shape = diamond; 63 ]; 64 accept_tos [ 65 label = "Accept\nToS?"; 66 shape = diamond; 67 ]; 68 withdrawal_action [ 69 label = "Withdrawal\nAction"; 70 shape = diamond; 71 ]; 72 select_exchange [ 73 label = "Select\nexchange"; 74 shape = rect; 75 ]; 76 tos [ 77 label = "ToS"; 78 shape = rect; 79 ]; 80 withdraw [ 81 label = "Confirm\nwithdrawal"; 82 shape = rect; 83 ]; 84 transactions [ 85 label = "List of\nTransactions"; 86 shape = oval; 87 ]; 88 89 default_exchange -> tos_changed [label="Yes"]; 90 default_exchange -> select_exchange [label="No"]; 91 tos_changed -> tos [label="Yes"]; 92 tos_changed -> withdraw [label="No"]; 93 select_exchange -> tos_accepted; 94 tos_accepted -> tos_changed [label="Yes"]; 95 tos_accepted -> tos [label="No"]; 96 tos -> accept_tos; 97 accept_tos -> withdraw [label="Yes"]; 98 accept_tos -> select_exchange [label="No"]; 99 withdraw -> withdrawal_action; 100 withdraw -> select_exchange [label="Change Exchange"]; 101 withdrawal_action -> transactions [label="Confirm"]; 102 103 { rank=same; tos_accepted; tos_changed; } 104 { rank=same; select_exchange; tos; } 105 { rank=same; withdrawal_action; withdraw; } 106 } 107 108 This enables the user to change the current exchange at any time in the process. 109 It ensures that the latest version of the exchange's terms of service have been accepted by the user 110 before allowing them to confirm the withdrawal. 111 112 Some special regional or test currencies might have only a single known exchange. 113 For those, the wallet should not offer the option to change an exchange. 114 115 After confirming the withdrawal, 116 the user is brought to the list of transactions of the current currency. 117 It will include a pending ``TransactionWithdrawal`` which might require additional user confirmation 118 such as a two-factor-authentication step with the bank. 119 120 1. The bank transfer happens immediately 121 2. A second factor is required which is "detached", 122 i.e. you have to press "confirm" on a physical Taler ATM, 123 or a Taler cashier has to do a final "confirm" on their device. 124 3. The bank provides a ``bankConfirmationUrl`` that the user needs to visit. 125 126 If the withdrawal proceeds very quickly, 127 the ``TransactionWithdrawal`` might not show as pending 128 and its effective amount is added to the displayed balance right away. 129 130 Alternatives 131 ============ 132 133 We considered and rejected the following alternatives: 134 135 * Do not allow more than one exchange to make Taler simpler to use and understand: 136 Taler wants to allow custom exchanges for custom currencies 137 and foster competition between exchanges for the same currency 138 to provide the best possible service to users at the lowest fee. 139 * Do not require acceptance to terms of service: 140 Having these terms and prompting the user to accept them 141 is a legal and business requirement in many jurisdictions, 142 so Taler needs to support them. 143 However, Taler encourages exchanges to keep their terms as short and simple as possible. 144 145 Discussion / Q&A 146 ================ 147 148 * Should wallets pre-set a default exchange for the most common currencies, 149 so that users will not be burdened to understand exchanges and their fee structures 150 when making their first withdrawal? 151 This could increase user retention, but discourage 152 * What should happen when an exchange changes its terms of service 153 and the user wants to use the funds stored there, 154 but does not initiate a new withdrawal with that exchange?