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