README.md (5111B)
1 # GNU Taler Point of Sale merchant terminal 2 3 This merchant point of sale terminal Android app allows sellers to 4 5 * process customers’ orders by adding or removing products, 6 * calculate the amount owed by the customer and 7 * let the customer make a Taler payment via QR code or NFC. 8 9 ## Building 10 11 You can import the project into Android Studio 12 or build it with Gradle on the command line (from the repository root): 13 14 $ ./bootstrap 15 $ ./gradlew :merchant-terminal:build 16 17 More information can be found in the 18 [Taler developer manual](https://docs.taler.net/developers-manual.html#build-apps-from-source). 19 20 ## Payment terminals 21 22 Card terminals are organised as providers: one ecosystem per provider, each with 23 its own SDK, settings and readers. Settings → Payment terminals holds a master 24 switch for the feature and opens the provider list; each provider there has its own 25 switch and its own settings screen. A provider is only reached by the app when both 26 the master switch and its own switch are on. 27 28 The terminal icon on the amount entry, inventory and payment screens opens a status 29 dialog summarising every active provider. Connection state is refreshed while the 30 app is resumed; being enabled or having a saved reader does not imply that the 31 reader is connected. Turning either switch off keeps stored settings and the 32 provider's session, so re-enabling does not require pairing again. Merchant logout 33 turns everything off and clears every provider session. 34 35 ### Packaging 36 37 The SumUp SDK is bundled unconditionally today, which costs roughly 22 MB in the 38 APK: the SDK itself plus the sqlcipher native libraries it depends on. 39 40 Android offers no way to add a terminal SDK after installation outside Google Play. 41 On-demand delivery needs an App Bundle and the proprietary Play Feature Delivery 42 library, split APKs cannot be installed from F-Droid or by sideloading, and the SDK 43 declares activities, services and permissions that only the installed manifest can 44 provide, so runtime class loading cannot work either. The intended direction is 45 therefore a companion app per ecosystem, talking to the POS over a standard 46 interface; [PaymentOption] is already that seam, and such an app would appear as one 47 more option in the registry. 48 49 ### Adding a provider 50 51 Implement `TerminalProvider` (in `terminal/TerminalProvider.kt`) and list it in the 52 `TerminalRegistry` of the flavour that bundles it. The provider owns its status 53 ladder, its activity result contracts and the composable for its own settings 54 screen; navigation, the settings screens and the status indicator adapt on their 55 own. `TerminalRegistry.initialize` runs any SDK startup the flavour needs. 56 57 ### Taler devices 58 59 The POS supports external Taler displays over USB and Bluetooth for payment and 60 refund links. Connect and manage displays under GNU Taler → Manage displays. 61 62 ### SumUp setup 63 64 The app uses a bundled SumUp affiliate key by default. Merchants sign in with their 65 own SumUp account. A different affiliate key can be set under Advanced in the 66 SumUp settings. 67 68 Supply the bundled key when building: 69 70 $ ./gradlew :merchant-terminal:assembleDebug -PsumupAffiliateKey=<key> 71 72 Alternatively, set `SUMUP_AFFILIATE_KEY` in the environment or `sumupAffiliateKey` 73 in `~/.gradle/gradle.properties`. 74 75 Open Settings → Payment terminals → SumUp and select Pair reader to sign in 76 and connect a card reader. 77 78 ### Paying in several parts 79 80 Enable cash or card payments to split a bill, with Taler covering the remaining 81 balance. Requires merchant backend protocol v42 or newer. Resume unfinished 82 checkouts from History using the same merchant account. Verify unresolved card 83 payments with the provider before continuing. 84 85 ### Card refunds 86 87 SumUp refunds are currently unavailable in the POS. Use SumUp's app or another 88 refund method. 89 90 ## Testing 91 92 Run unit tests with JDK 21: 93 94 $ ./gradlew :merchant-terminal:testDebugUnitTest 95 96 Testing SumUp payments requires an affiliate key, merchant account and compatible 97 card reader. 98 99 ## Kotlin formatting 100 101 Use Android Studio and ktlint with the module's `.editorconfig`: four-space 102 indentation, a 120-character line limit and Allman braces. 103 104 ```sh 105 ./gradlew :merchant-terminal:formatKotlin 106 ./gradlew :merchant-terminal:checkKotlinFormat :merchant-terminal:ktlintCheck 107 ``` 108 109 If Android Studio is not detected, set `ANDROID_STUDIO_HOME` to its installation 110 directory (`Contents` on macOS). 111 112 ## Screenshots 113 114 Use one capture flow with named subsets: 115 116 ```sh 117 python3 merchant-terminal/scripts/capture-screenshots.py --set tutorials --serial emulator-5560 118 python3 merchant-terminal/scripts/capture-screenshots.py --set play-store --serial emulator-5560 119 ``` 120 121 `tutorials` produces raw screenshots. `play-store` captures the selected screens 122 and applies the approved phone/tablet templates. `--set all` runs both. 123 Outputs are images only under `merchant-terminal/build/screenshots`. 124 125 See [SCREENSHOTS.md](SCREENSHOTS.md) for setup, filters, and rebuilding the Play 126 Store images from existing captures. The [template sources](design/google-play/README.md) 127 contain the editable layouts, headlines, font and logo.