088-wallet-withdraw.rst (5189B)
1 DD 88: Wallet Withdrawal Experience 2 ################################### 3 4 :Design status: Accepted 5 :Implementation status: Partial 6 :DD shepherd: TBD 7 :Historical contributors: Vlada Svirsh 8 :First published: 2026-03-01 9 :Last substantive change: 2026-05-03 10 :Implementation evidence: ``taler-android`` (2026-03-04); no corresponding iOS/WebExtension implementation was established 11 12 Summary 13 ======= 14 This document describes withdraw flow and experience in wallet. It defines what Android, iOS and WebExtension 15 should follow in order to have a coherent withdrawal experience between platforms. 16 17 Motivation 18 ========== 19 We want user to have smooth withdrawal experience independent of the platform they are using. 20 21 Requirements 22 ============ 23 24 Proposed Solution 25 ================= 26 27 Withdraw 28 ~~~~~~~~ 29 30 .. image:: wallet-designs/cta-withdraw-1.png 31 :width: 50% 32 33 After choosing "Withdraw" action or pressing "Withdraw digital cash" button from "Empty wallet screen", the user is presented with this screen. 34 The keyboard for amount entry automatically opens. 35 The Withdraw button is disabled until a valid amount is entered. Once a valid amount is provided, the button is enabled and displayed with the primary color. 36 37 .. image:: wallet-designs/cta-withdraw-2.png 38 :width: 50% 39 40 The user can select a currency from a dropdown list. 41 A warning icon appears next to the currency selector; tapping it opens a dialog (see next image). 42 The warning icon uses the warning color from the :doc:`066-wallet-color-scheme`. 43 44 .. image:: wallet-designs/cta-withdraw-3.png 45 :width: 50% 46 47 The warning dialog displays the message: 48 "The service provider is not trusted by the developers of this wallet." 49 50 .. image:: wallet-designs/cta-withdraw-4.png 51 52 If applicable, fees are displayed below the amount input field. 53 Below the amount section, amount shortcuts defined by the exchange are shown for quick selection. 54 55 More details about the prototype are available here: 56 `Penpot Prototype <https://penpot.taler.net/#/workspace?team-id=826af720-982c-8096-8006-0dbdd6a758c1&file-id=29e68e1b-4b36-81a2-8006-bf7630bda762&page-id=29e68e1b-4b36-81a2-8006-bf7630bda763&layout=assets>`_ 57 58 Withdraw pending 59 ~~~~~~~~~~~~~~~~ 60 61 .. image:: wallet-designs/cta-withdraw-pending-1.png 62 63 This screen is shown after the user confirms the withdrawal **if only** 1 QR code available 64 for withdrawal digital cash. 65 66 Screen contains: 67 68 - Header with title "Withdraw pending" 69 - Date of withdrawal 70 - Exchange base_url 71 - Amount 72 - Fees 73 - Text: "Follow the instructions to enter the transfer details into your banking app:" 74 - Primary button "Wire transfers instructions" that opens a screen with instructions for wire transfer (see next image) 75 - Text: "Or share this QR code with your banking app to withdraw digital cash" 76 - Swiss QR code with black and white flag inside 77 - Secondary button "Share" that opens the system share dialog to share the QR code with banking app 78 79 Wire transfer instructions 80 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 81 82 .. image:: wallet-designs/cta-withdraw-wire-instructions.png 83 84 This screen is shown after the user clicks on "Wire transfers instructions" button from "Withdraw pending" screen. 85 86 Screen contains: 87 88 - Header with title "Wire transfer instructions" 89 - Text: "You need to transfer **$amount-with-fees** from your regular bank account to the payment service to receive 90 **$amount** as digital cash in this wallet 91 92 - Warning icon (color warning ``#f99c06``) and text: "$accepted-countries bank accounts only" 93 - Divider 94 - Text: "**Step 1:** If you don't already have it in your banking favorites list, then copy and paste **IBAN, recipient name, address** and **amount** into the matching fields in your banking app or website (and save it for next time):" 95 96 - List of details to copy and paste: 97 98 - IBAN 99 - Recipient name 100 - Address 101 - Amount 102 103 - Text: "**Step 2:** Copy this code and paste it into the subject/purpose field in your banking app or website:" 104 - Warning banner (color WarningContainer ``#fdedd3``, rounding radius 15) with warning icon and text: "This is mandatory, otherwise your money will not arrive in this wallet" 105 - Subject to copy and paste 106 - Text: "**Step 3:** Finish the wire transfer of **$amount-with-fees** in your banking app or website, then this withdrawal will proceed automatically. Depending on your bank the transfer can take from minutes up to 2 business days. Please be patient." 107 - Secondary button "Share" that opens the system share dialog to share the wire transfer instructions with the banking app 108 109 Test Plan 110 ========= 111 112 (If this DD concerns a new or changed feature, describe how it can be tested.) 113 114 Definition of Done 115 ================== 116 117 (Only applicable to design documents that describe a new feature. While the 118 DoD is not satisfied yet, a user-facing feature **must** be behind a feature 119 flag or dev-mode flag.) 120 121 Alternatives 122 ============ 123 124 * Alternative for input amount to simplify implementing 125 * Higher positioning of elements, so shortcuts are not hiden by keyboard 126 127 .. image:: wallet-designs/cta-withdraw-alt-1.png 128 :width: 50% 129 130 131 Drawbacks 132 ========= 133 134 Discussion / Q&A 135 ================ 136 137 (This should be filled in with results from discussions on mailing lists / personal communication.)