094-discounts-passes-wallet.rst (5982B)
1 DD 94: Discounts & Passes Wallet UI 2 ################################### 3 4 :Design status: Accepted 5 :Implementation status: Partial 6 :DD shepherd: TBD 7 :Historical contributors: Vlada Svirsh 8 :First published: 2026-04-29 9 :Last substantive change: 2026-05-29 10 :Implementation evidence: ``taler-ios`` (2026-06-22; 2026-06-24); ``taler-typescript-core`` (2026-08-11, not merged into the reviewed HEAD) 11 12 Summary 13 ======= 14 15 This document describes the design and behavior of all wallet screens related to discounts and passes. It defines a unified 16 way to present, manage, and display these entities across the wallet, including their states, structure, and visual representation. 17 18 Motivation 19 ========== 20 21 Merchants can provide users with discounts or passes that apply to specific 22 products or services. In protocol terminology, a user-facing "pass" is a token 23 family of kind ``subscription``; ``pass`` is not a separate token-family kind. 24 The wallet must support: 25 26 * Clear presentation of available discounts and passes 27 * Ability for users to review and apply them during checkout 28 * Overview of all owned items, including: 29 30 - Currently active 31 - Not yet active (future validity) 32 - Available for use 33 34 A consistent design ensures users can easily understand what benefits they have, when they can use them, and how they 35 affect their purchases. 36 37 38 Requirements 39 ============ 40 41 - The wallet must provide separate pages for discounts and passes. 42 - Discounts and passes must be grouped into two tabs: 43 44 * Available: active items and items valid in the future. 45 * Expired: expired, redeemed, or used items. 46 47 - Each discount and pass must be displayed as a card with consistent layout and styling. 48 - Cards must show the item name, description, merchant information, validity information, and quantity badge when applicable. 49 - Active items must be visually distinguished from future items. 50 - Future items must clearly show when they become valid. 51 - Expired items must clearly show their full validity period. 52 - Redeemed discounts must provide a link to the related order details page. 53 - Used passes must provide a link to related orders when applicable. 54 - The quantity badge must be hidden when the user owns only one item of the same type. 55 - The order details page must show discounts and passes that are applied to the current order. 56 - The order details page must show discounts and passes that the user will receive after completing the purchase. 57 - The review order section must be expandable and collapsed by default. 58 - Payment options must clearly indicate the selected option. 59 - The UI must use existing theme colors. 60 61 Proposed Solution 62 ================= 63 64 Discounts & Passes Pages 65 ------------------------ 66 67 Available 68 ~~~~~~~~~ 69 70 .. list-table:: 71 :widths: 50 50 72 73 * - .. image:: wallet-designs/discounts-page.png 74 :width: 100% 75 76 - .. image:: wallet-designs/passes-page.png 77 :width: 100% 78 79 Inside card next information is displayed: 80 81 - Name of the discount or pass 82 - Description 83 - For discount card: "Redeemable at:" with the merchant name. For pass card: "Provided by:" with the merchant name. 84 - Validity section: 85 86 * For active items: "Valid until" with the expiration date. Background color is SecondaryContainer. Text color is onSecondaryContainer. 87 * For future items: "Valid from" with the start date. 88 - Badge used to indicate number of items of the same type. If only one item of the same type is owned, the badge is not shown. 89 90 * For active items: badge background color is Primary. Text color is onPrimary. 91 * For future items: badge background color is SurfaceVariant. Text color is onSurfaceVariant. 92 93 Expired 94 ~~~~~~~ 95 96 .. list-table:: 97 :widths: 50 50 98 99 * - .. image:: wallet-designs/discounts-page-ex.png 100 :width: 100% 101 102 - .. image:: wallet-designs/passes-page-ex.png 103 :width: 100% 104 105 Inside card next information is displayed: 106 107 - Name of the discount or pass 108 - Description 109 - For discount card: 110 111 * Redeemed: "Redeemable at" + merchant name + "on" + redeemed date. Text button with ``primary color`` "View order" with the link to the order details page. 112 * Not redeemed: "Was redeemable at:" with the merchant name. 113 114 - For pass card: 115 116 * "Provided by:" with the merchant name. 117 * For used pass show text button Primary color "View orders" with the link to the orders list. 118 119 - Validity section: "Validity period" and date range. 120 - Badge used to indicate number of items of the same type. If only one item of the same type is owned, the badge is not shown. 121 122 123 124 125 Order details page 126 ------------------ 127 .. image:: wallet-designs/order-discounts-passes-uncollapsed.png 128 :width: 50% 129 130 On this page next information is displayed: 131 132 - Merchant logo 133 - Merchant name 134 - Merchant address 135 - "Review order" section collapsed by default. Linear blur is applied to give a hint to user what is inside this section. When user clicks on "Review order" section, the section expands and blur is removed. In this section next information is displayed: 136 137 * Order summary 138 * List of products with: 139 140 - Picture (if available at least for one product) 141 - Name 142 - Description (if present and different from order name) 143 - Quantity with unit name 144 - Price per unit 145 - Total price, calculated as ``(product price * quantity)`` and currency code 146 147 - "Payment options" section. Chosen option has ``primary color`` border, primary button "Confirm payment" and ``primaryContainer`` background for list of discounts/passes. For each option next information is displayed: 148 149 * Price 150 * "Spend now:" section with the list of discounts and passes applied to the order. 151 * "Get with your purchase:" section with the list of discounts and passes that will be added to the wallet after the order is completed. 152 153 Test Plan 154 ========= 155 156 157 Definition of Done 158 ================== 159 160 Alternatives 161 ============ 162 Instead of blurring the "Review order" section, we could use fade out effect for collapsed section. 163 164 Drawbacks 165 ========= 166 167 Discussion / Q&A 168 ================