pretix-sattleme 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. pretix_sattleme-1.0.0/CHANGELOG.md +44 -0
  2. pretix_sattleme-1.0.0/LICENSE +21 -0
  3. pretix_sattleme-1.0.0/MANIFEST.in +16 -0
  4. pretix_sattleme-1.0.0/PKG-INFO +515 -0
  5. pretix_sattleme-1.0.0/README.md +485 -0
  6. pretix_sattleme-1.0.0/SECURITY.md +30 -0
  7. pretix_sattleme-1.0.0/pretix_sattleme/__init__.py +4 -0
  8. pretix_sattleme-1.0.0/pretix_sattleme/apps.py +44 -0
  9. pretix_sattleme-1.0.0/pretix_sattleme/checks.py +521 -0
  10. pretix_sattleme-1.0.0/pretix_sattleme/display.py +180 -0
  11. pretix_sattleme-1.0.0/pretix_sattleme/invoices.py +398 -0
  12. pretix_sattleme-1.0.0/pretix_sattleme/links.py +42 -0
  13. pretix_sattleme-1.0.0/pretix_sattleme/locale/de/LC_MESSAGES/django.po +810 -0
  14. pretix_sattleme-1.0.0/pretix_sattleme/locale/de_Informal/LC_MESSAGES/django.po +808 -0
  15. pretix_sattleme-1.0.0/pretix_sattleme/locale/django.pot +661 -0
  16. pretix_sattleme-1.0.0/pretix_sattleme/locale/fr/LC_MESSAGES/django.po +802 -0
  17. pretix_sattleme-1.0.0/pretix_sattleme/locale/it/LC_MESSAGES/django.po +801 -0
  18. pretix_sattleme-1.0.0/pretix_sattleme/migrations/0001_initial.py +55 -0
  19. pretix_sattleme-1.0.0/pretix_sattleme/migrations/__init__.py +0 -0
  20. pretix_sattleme-1.0.0/pretix_sattleme/models.py +208 -0
  21. pretix_sattleme-1.0.0/pretix_sattleme/payment.py +379 -0
  22. pretix_sattleme-1.0.0/pretix_sattleme/prices.py +66 -0
  23. pretix_sattleme-1.0.0/pretix_sattleme/qr.py +44 -0
  24. pretix_sattleme-1.0.0/pretix_sattleme/sdk.py +62 -0
  25. pretix_sattleme-1.0.0/pretix_sattleme/shredding.py +141 -0
  26. pretix_sattleme-1.0.0/pretix_sattleme/signals.py +119 -0
  27. pretix_sattleme-1.0.0/pretix_sattleme/static/pretix_sattleme/pay.css +20 -0
  28. pretix_sattleme-1.0.0/pretix_sattleme/static/pretix_sattleme/pay.js +122 -0
  29. pretix_sattleme-1.0.0/pretix_sattleme/static/pretix_sattleme/sattleme-icon.svg +1 -0
  30. pretix_sattleme-1.0.0/pretix_sattleme/tasks.py +24 -0
  31. pretix_sattleme-1.0.0/pretix_sattleme/templates/pretix_sattleme/checkout_payment_confirm.html +7 -0
  32. pretix_sattleme-1.0.0/pretix_sattleme/templates/pretix_sattleme/checkout_payment_form.html +11 -0
  33. pretix_sattleme-1.0.0/pretix_sattleme/templates/pretix_sattleme/control.html +96 -0
  34. pretix_sattleme-1.0.0/pretix_sattleme/templates/pretix_sattleme/pay.html +173 -0
  35. pretix_sattleme-1.0.0/pretix_sattleme/templates/pretix_sattleme/pending.html +57 -0
  36. pretix_sattleme-1.0.0/pretix_sattleme/templates/pretix_sattleme/settings.html +42 -0
  37. pretix_sattleme-1.0.0/pretix_sattleme/urls.py +15 -0
  38. pretix_sattleme-1.0.0/pretix_sattleme/views.py +124 -0
  39. pretix_sattleme-1.0.0/pretix_sattleme.egg-info/PKG-INFO +515 -0
  40. pretix_sattleme-1.0.0/pretix_sattleme.egg-info/SOURCES.txt +59 -0
  41. pretix_sattleme-1.0.0/pretix_sattleme.egg-info/dependency_links.txt +1 -0
  42. pretix_sattleme-1.0.0/pretix_sattleme.egg-info/entry_points.txt +2 -0
  43. pretix_sattleme-1.0.0/pretix_sattleme.egg-info/requires.txt +2 -0
  44. pretix_sattleme-1.0.0/pretix_sattleme.egg-info/top_level.txt +1 -0
  45. pretix_sattleme-1.0.0/pyproject.toml +162 -0
  46. pretix_sattleme-1.0.0/scripts/translations.py +159 -0
  47. pretix_sattleme-1.0.0/setup.cfg +52 -0
  48. pretix_sattleme-1.0.0/setup.py +41 -0
  49. pretix_sattleme-1.0.0/tests/__init__.py +0 -0
  50. pretix_sattleme-1.0.0/tests/conftest.py +323 -0
  51. pretix_sattleme-1.0.0/tests/test_changed_orders.py +303 -0
  52. pretix_sattleme-1.0.0/tests/test_checks.py +831 -0
  53. pretix_sattleme-1.0.0/tests/test_display.py +128 -0
  54. pretix_sattleme-1.0.0/tests/test_invoices.py +709 -0
  55. pretix_sattleme-1.0.0/tests/test_migrations.py +10 -0
  56. pretix_sattleme-1.0.0/tests/test_one_payable_invoice.py +185 -0
  57. pretix_sattleme-1.0.0/tests/test_provider.py +638 -0
  58. pretix_sattleme-1.0.0/tests/test_shredding.py +184 -0
  59. pretix_sattleme-1.0.0/tests/test_translations.py +142 -0
  60. pretix_sattleme-1.0.0/tests/test_views.py +314 -0
@@ -0,0 +1,44 @@
1
+ # Changelog
2
+
3
+ Versions of `pretix-sattleme` ([semantic versioning](https://semver.org)).
4
+
5
+ ## 1.0.0 - 2026-11-22
6
+
7
+ First version, on the sattle.me checkout SDK 1.0.0 (`sattleme-checkout`, any 1.x release), for
8
+ pretix 2026.7 and later.
9
+
10
+ - The payment method **Bitcoin (sattle.me)**: its integration key, checked when saved and never
11
+ shown again, how long an invoice can be paid, and its name and description at checkout.
12
+ - The method offered only for a price the SDK takes: in a currency of its table, for an amount of
13
+ at most the decimals it prices that currency with (the order's total with the method's fee, or
14
+ what the order owes when its customer changes to it). Its settings page says when the event's
15
+ currency cannot be used, or only for amounts in whole units.
16
+ - An invoice per payment, made once the order is confirmed, for a random reference; the payment
17
+ locked while it is made, so that two requests at once get one invoice.
18
+ - A payment page in the shop: the QR code (made on the server), the invoice and the address to
19
+ copy, the time left, the rest of an on-chain underpayment, the confirmations; updated on its
20
+ own, usable without JavaScript, and in pretix's widget too.
21
+ - Payments checked for the payment page, by a chain of Celery tasks per invoice (with a check just
22
+ before the end of its grace period) and by pretix's periodic tasks; confirmed on a `paid` status
23
+ only, failed when expired unpaid, left pending for the organizer with a note when expired
24
+ underpaid; an order whose confirmed payment pretix failed to mark paid marked paid by the next
25
+ check.
26
+ - On-chain payments paid at 3 confirmations on the explorer the SDK reads: mempool.space, or the
27
+ merchant's own Bitcoin node when the merchant's app names one, with its fallback.
28
+ - Invoices that end 5 minutes before pretix's deadlines (the order's last date of payments and
29
+ expiry), payments made in time confirmed however long their confirmations take, and an order
30
+ kept from expiring while its on-chain payment is being confirmed (brought back when pretix
31
+ expired it before a check saw that payment, its products allowing). Another payment method, or
32
+ a new invoice, only once an invoice ended unpaid, as a check after its end finds it: an order
33
+ is never paid twice by its customer.
34
+ - An order whose total changed after its invoice was made (changed, canceled or paid otherwise),
35
+ then paid, never completed automatically: the payment stays pending, with a note of the amount
36
+ received and what the order owes now, for the organizer to confirm by hand. A payment of
37
+ another amount in sats than the invoice's is noted too: an overpayment, or less that the
38
+ merchant accepted in the sattle.me app (its tolerance, or by hand what an order underpaid
39
+ on-chain received), confirmed as paid.
40
+ - pretix's data shredder « Payment information » also removes what leads to the customer's coins:
41
+ the deposit address and the transactions, from the payments' information, from pretix's log
42
+ entries of them, and from their invoices.
43
+ - The payment's details in pretix's backend and REST API, the order's history; translations in
44
+ German (formal and informal), French and Italian.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Swiss Bitcoin Pay Sàrl
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,16 @@
1
+ recursive-include pretix_sattleme/static *
2
+ recursive-include pretix_sattleme/templates *
3
+ recursive-include pretix_sattleme/locale *
4
+ # Compiled by the build (setup.py) from the catalogs, never shipped unseen.
5
+ recursive-exclude pretix_sattleme/locale *.mo
6
+ include LICENSE
7
+ include README.md
8
+ include CHANGELOG.md
9
+ include SECURITY.md
10
+ # The build compiles the translations with it.
11
+ include scripts/translations.py
12
+ recursive-include tests *.py
13
+ # They read the SDK pinned in sdk/, which the sdist does not hold.
14
+ exclude tests/test_sdk_pin.py
15
+ exclude tests/test_price_vectors.py
16
+ global-exclude *.py[cod] __pycache__
@@ -0,0 +1,515 @@
1
+ Metadata-Version: 2.4
2
+ Name: pretix-sattleme
3
+ Version: 1.0.0
4
+ Summary: Bitcoin payments (Lightning and on-chain) for pretix with sattle.me: paid straight to the organizer's wallet.
5
+ Author: sattle.me
6
+ Maintainer: sattle.me
7
+ License-Expression: MIT
8
+ Project-URL: homepage, https://sattle.me
9
+ Project-URL: repository, https://github.com/sattleme/checkout-pretix
10
+ Project-URL: changelog, https://github.com/sattleme/checkout-pretix/blob/main/CHANGELOG.md
11
+ Project-URL: issues, https://github.com/sattleme/checkout-pretix/issues
12
+ Keywords: pretix,bitcoin,lightning,payments,sattleme
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Environment :: Web Environment
15
+ Classifier: Framework :: Django
16
+ Classifier: Intended Audience :: Other Audience
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Office/Business :: Financial
24
+ Requires-Python: >=3.11
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: sattleme-checkout<2,>=1.0
28
+ Requires-Dist: qrcode>=7.4
29
+ Dynamic: license-file
30
+
31
+ # sattle.me for pretix
32
+
33
+ A payment plugin for [pretix](https://pretix.eu): customers pay their orders in bitcoin, in
34
+ Lightning or on-chain, and the bitcoin goes straight to the organizer's
35
+ [sattle.me](https://sattle.me) wallet. It is built on the
36
+ [sattle.me checkout SDK](https://pypi.org/project/sattleme-checkout/)
37
+ ([source](https://github.com/sattleme/checkout-python)), which makes and checks the invoices:
38
+ no sattle.me server, no API key of a third party, and the integration key can make invoices that
39
+ pay the organizer, never spend the funds.
40
+
41
+ - [How it works](#how-it-works)
42
+ - [Requirements](#requirements)
43
+ - [Installation](#installation)
44
+ - [Configuration](#configuration)
45
+ - [Payments and orders](#payments-and-orders)
46
+ - [Background checks](#background-checks)
47
+ - [Security](#security)
48
+ - [Privacy](#privacy)
49
+ - [Known limits](#known-limits)
50
+ - [Troubleshooting](#troubleshooting)
51
+ - [Development](#development)
52
+ - [Releases](#releases)
53
+ - [License](#license)
54
+
55
+ ## How it works
56
+
57
+ 1. At checkout, the customer chooses **Bitcoin** (or the name the organizer gives the method).
58
+ Once they confirm their order, the plugin asks the SDK for the invoice of the payment: a
59
+ Lightning invoice, a deposit address of the organizer's wallet, or both, depending on the
60
+ amount (see [the SDK](https://github.com/sattleme/checkout-python#on-chain-payments)).
61
+ 2. The customer lands on a payment page of the shop, in its design and language: one QR code of
62
+ the invoice (BIP-21 with `lightning=`, or `lightning:`), a button that opens their wallet with
63
+ it, the Lightning invoice and the address to copy, the amount (in bitcoin, in sats and in the
64
+ order's currency), and the time left to pay.
65
+ 3. The page follows the payment on its own. Once the SDK reports it **paid**, the plugin confirms
66
+ the pretix payment: the order is paid, the tickets are sent as usual, and the page takes the
67
+ customer to the order.
68
+
69
+ The page is rendered on the server (the QR code is an inline SVG); its small script, a file of the
70
+ plugin, only counts down, copies, and reloads the page when the payment moved on. Without
71
+ JavaScript, the page offers a button to check the payment.
72
+
73
+ In [pretix's widget](https://docs.pretix.eu/guides/widget/), on the organizer's own site, it is
74
+ the same: the payment page shows in the widget's frame (or in a new tab, where the widget opens
75
+ the checkout so), and its copy buttons work there too.
76
+
77
+ ## Requirements
78
+
79
+ - pretix **2026.7** or later, on Python **3.11** to **3.14**: the feature releases pretix
80
+ publishes security fixes for. The plugin's tests run against pretix 2026.7.4, 2026.8.2 and
81
+ 2026.9.1, and its end-to-end test against their Docker images.
82
+ - pretix's periodic tasks (`runperiodic`, from cron) running, and preferably its task workers
83
+ (Celery), as in any production installation of pretix (see
84
+ [Background checks](#background-checks)).
85
+ - A merchant account of sattle.me, and an **integration** created in its app.
86
+ - **Outbound connections** from the pretix server (never from the customer's browser), direct:
87
+ the SDK does not use the environment's proxy settings.
88
+ - The merchant's **Nostr relays**, over WebSocket (TLS): those the integration key names, or
89
+ the merchant's app.
90
+ - The merchant's **Lightning address** (breez.tips for a sattle.me account) and the URLs its
91
+ provider gives (its callback, its verify URLs), over HTTPS.
92
+ - The **rate sources**, one after the other until one answers: CoinGecko, mempool.space,
93
+ Coinbase, Kraken, OpenNode.
94
+ - For an invoice with a deposit address, the **explorer**: **mempool.space**, or the
95
+ merchant's own **Bitcoin node** when the merchant's app names one (over HTTPS, or HTTP for a
96
+ node on the merchant's local network), with mempool.space as its fallback unless the
97
+ merchant chose none; and **api.blockcypher.com** for a transaction no check saw in time.
98
+
99
+ Every request, and the handshake of each WebSocket, says `User-Agent: sattleme-Checkout/1`.
100
+ See the SDK's [What goes where](https://github.com/sattleme/checkout-python#what-goes-where).
101
+
102
+ ## Installation
103
+
104
+ The plugin is distributed on [pretix's marketplace](https://marketplace.pretix.eu/), its package
105
+ on PyPI (`pretix-sattleme`). Into the Python environment of your pretix installation:
106
+
107
+ ```shell
108
+ pip install pretix-sattleme
109
+ python -m pretix migrate
110
+ python -m pretix rebuild
111
+ ```
112
+
113
+ then restart pretix's web and task workers. pip installs the SDK (`sattleme-checkout`, any 1.x
114
+ release) with it. To update the plugin, the same commands, with `pip install -U pretix-sattleme`.
115
+
116
+ With pretix's Docker image, build your own image with the plugin, as pretix's documentation
117
+ shows for any plugin
118
+ ([Install a plugin](https://docs.pretix.eu/self-hosting/installation/docker_smallscale/)):
119
+
120
+ ```dockerfile
121
+ FROM pretix/standalone:stable
122
+ USER root
123
+ RUN pip3 install pretix-sattleme
124
+ USER pretixuser
125
+ RUN cd /pretix/src && make production
126
+ ```
127
+
128
+ then run that image instead of `pretix/standalone`: it migrates the database on start. Build it
129
+ again to update the plugin, or pretix.
130
+
131
+ ## Configuration
132
+
133
+ 1. In the sattle.me app, create an integration for your shop and copy its secret key
134
+ (`sattleme_ck_…`).
135
+ 2. In pretix, open your event, **Settings → Plugins**, and enable **sattle.me** (with the brand's
136
+ icon).
137
+ 3. Open **Settings → Payment → Bitcoin (sattle.me)**, enable the payment method, and enter the
138
+ key. It is checked when you save it: the SDK refuses what is not an integration key, then
139
+ reads the integration on the merchant's relays, so that the key of an integration removed in
140
+ the app, or of one the relays do not know, is refused. Once saved, it is never shown again.
141
+ 4. **Time to pay**: how long the customer has to pay an invoice, 1 to 60 minutes (15 by default).
142
+ 5. Optionally, the **name** of the method and the **description** shown at checkout, in each of
143
+ the event's languages (Markdown, as pretix's own methods take it). Without them, the method
144
+ is called "Bitcoin", and the checkout says how a Bitcoin payment goes.
145
+
146
+ Change the key only while no Bitcoin payment is pending: each check uses the key set at its time,
147
+ and an invoice with a deposit address made under another integration's key would be judged without
148
+ its records in the merchant's registry (its lease, its tolerance, the invoices of its rest).
149
+
150
+ pretix's usual settings of a payment method apply as well: fees, availability dates, minimum and
151
+ maximum totals, sales channels, countries, hiding the method behind a link.
152
+
153
+ **When the method is offered.** At checkout, and to a customer changing their order's payment
154
+ method, only for a payment whose price the SDK takes (its
155
+ [Prices in a currency](https://github.com/sattleme/checkout-python#prices-in-a-currency)): in a
156
+ currency of the SDK's table (`currency_digits`), for an amount (the order's total with this
157
+ method's fee, or what the order owes then) of at most the decimals the SDK prices that currency
158
+ with. In most currencies, that is every amount of pretix. In a few, the SDK prices in whole units
159
+ while pretix rounds to cents (ISK, RSD or UGX, for instance): the method is offered for amounts in
160
+ whole units only. In a currency out of the table (a fund such as CHE, for instance), never. The
161
+ method's settings page says so, when the event's currency is one of those.
162
+
163
+ **Test mode.** sattle.me has no test network: in pretix's test mode too, payments are real
164
+ bitcoin payments, to the organizer's wallet. The checkout says so.
165
+
166
+ ## Payments and orders
167
+
168
+ | What the SDK reports | What the plugin does |
169
+ | ---------------------------------------- | ------------------------------------------------------------------------------- |
170
+ | An invoice was made | The pretix payment is **pending**; the customer goes to the payment page. |
171
+ | `open` | Waits. Another payment method only once a check after its end finds it expired. |
172
+ | `open` with `received` (on-chain, short) | The page shows what came and a QR code for the rest (the SDK asks for it). |
173
+ | `unconfirmed` | Waits for 3 confirmations (about 30 minutes), keeping the order from expiring. |
174
+ | `paid` (Lightning, on-chain, or both) | Confirms the pretix payment: the order is paid. |
175
+ | `paid`, the order owing another amount | Leaves it to the organizer, noting what came and what the order owes (below). |
176
+ | `paid` with `received` other than `sats` | Confirms it, noting both: what the merchant accepted, or an overpayment. |
177
+ | `expired` | The pretix payment **fails** (no email): the customer can pay again. |
178
+ | `expired` with `received` above 0 | Leaves it to the organizer, noting what reached the wallet (below). |
179
+
180
+ - **Only a `paid` status confirms a payment**, from the SDK's own check of the invoice that
181
+ payment holds, on the server: never because the customer's browser says so. A payment is
182
+ confirmed once, through pretix's own confirmation, whichever check sees it first.
183
+ - **One payment, one reference.** Each payment gets a random reference (128 bits), stored before
184
+ the SDK is asked for its invoice, and never used for another payment: no deleted test order,
185
+ restored backup or other installation can share it. A try that follows a failed one (a
186
+ timeout, a worker stopped) asks for the same reference: the SDK then hands out the invoice it
187
+ may have made meanwhile, never a second one, or reports it paid: the page then says the payment
188
+ arrived, and the check that follows at once, in the background, confirms it.
189
+ - **The order locked.** The invoice is made with the payment and its order locked in the
190
+ database, as pretix locks them: two requests at once (a double click, two workers) get one
191
+ invoice.
192
+ - **One payable invoice per order.** A Lightning invoice cannot be revoked: until an invoice of
193
+ the order is known to have ended unpaid, the customer cannot choose another payment method, nor
194
+ get another Bitcoin invoice (the page says until when), so that the order is never paid twice.
195
+ Known from its final status only, `expired` with nothing received, which a check after its end
196
+ (its grace period included) gives: its time being over is not enough, a payment of its last
197
+ seconds or an on-chain one dated in time is found by that check, however late it comes
198
+ (without Celery workers) or long it fails (the merchant's Lightning address not answering).
199
+ An invoice that ended underpaid keeps the order too, until the organizer settles it
200
+ (Underpayments, below). When the organizer cancels or changes the order meanwhile, or marks it
201
+ paid, pretix asks the plugin to cancel the payment: it refuses until the invoice's final status
202
+ is known, and pretix keeps the payment pending and says why in the order's history. The
203
+ invoice's checks go on.
204
+ - **An order changed after its invoice.** When an invoice is found paid, the plugin compares its
205
+ price with what the order owes then, in its currency: its total (none once canceled), less what
206
+ its other payments paid (a gift card, for one), net of what was refunded. When they differ (the
207
+ order was changed, canceled or paid otherwise after the invoice was made), the order is never
208
+ completed automatically. pretix has no state for an order the organizer must look at: the
209
+ payment stays pending, the order's history notes the amount received and what the order owes
210
+ now, and the organizer settles the difference with the customer, then confirms the payment by
211
+ hand (or cancels it). Meanwhile the customer's pages say so, and offer no other way to pay.
212
+ - **Deadlines.** An invoice never outlives the moment pretix would refuse its payment or free the
213
+ order's products: the order's last date of payments and its expiry (but for an order past its
214
+ expiry when late payments are accepted: that is a late payment, as pretix allows). The plugin
215
+ checks that each invoice ends in time, the SDK's 120 s of grace and the clock of the merchant's
216
+ Lightning address included, and 5 minutes before: its checks after its end come before the
217
+ deadline. A payment made in time is confirmed however long its confirmations took, and while
218
+ an on-chain payment is being confirmed, its order is kept from expiring. An order pretix
219
+ expired all the same before a check saw that payment (its periodic tasks running late, without
220
+ Celery workers) is brought back, as pretix's backend does, when its products are still
221
+ available; else pretix decides once the payment is confirmed (the order's history says why).
222
+ - **Underpayments.** When less than the amount comes on-chain in time, the page shows the rest,
223
+ as a Lightning invoice the SDK asks for. The merchant may accept an on-chain payment a little
224
+ short of the amount (its tolerance, set in the sattle.me app): the SDK then reports it `paid`.
225
+ The merchant may also accept by hand, in the app, what an order underpaid on-chain received:
226
+ the SDK then reports it `unconfirmed`, then `paid`, with `received` below `sats`, and the plugin
227
+ confirms it as with the tolerance, noting what came.
228
+ An invoice that ends underpaid all the same did not end unpaid: what came reached the wallet,
229
+ and paying the order again would pay it twice. Its payment stays pending, the order's history
230
+ notes what came, the customer's page asks them to contact the organizer, and the organizer
231
+ settles the difference: confirms the payment by hand, or cancels it for the customer to pay
232
+ again (and refunds what came).
233
+ - **Late payments.** A payment counts when it comes by the invoice's end, its grace period
234
+ included. An on-chain payment broadcast after that reaches the merchant's wallet (the address
235
+ is the wallet's) but pays no order: the SDK reports the invoice `expired` without it, the page
236
+ says it expired unpaid, and nothing of it is recorded in pretix. The customer contacts the
237
+ organizer, who finds it in the wallet (or on mempool.space, the address being in the payment's
238
+ details) and settles it by hand.
239
+ - **Refunds** are not automatic: a Lightning payment can only be refunded to an invoice of the
240
+ customer's, an on-chain one to an address of theirs, which pretix never asks. Refund the
241
+ customer from the wallet, then record the refund in pretix as a manual refund.
242
+ - The organizer sees in the payment's details the invoice's reference, amount and exchange rate,
243
+ the address, the transactions (linked to mempool.space), the proof of payment (preimage), the
244
+ last check and its error in plain words; the order's history logs the invoices made, the
245
+ payments being confirmed, the underpayments, the payments left to the organizer, those of
246
+ another amount than the invoice's, and why an invoice could not be made. pretix's
247
+ REST API gives the payment's reference, amount in sats, payment hash, address, expiry, last
248
+ status, and whether that status is final.
249
+
250
+ ## Background checks
251
+
252
+ The SDK has no webhooks: payments are checked, by the plugin, on the pretix server.
253
+
254
+ - While the customer's payment page is open: the page asks every few seconds, and the server
255
+ checks the invoice at most every 6 seconds.
256
+ - In the background, each invoice by a chain of Celery tasks: every minute while it can be paid,
257
+ once 10 seconds before the end of its grace period (an on-chain payment a check lists by then
258
+ came in time, without asking BlockCypher) and once 10 seconds after, then every five minutes
259
+ until its final status is known (an on-chain payment being confirmed). After failed checks,
260
+ once the invoice has ended: one minute, then twice as long each time, up to every 30 minutes.
261
+ - pretix's periodic tasks restart the checks of an invoice whose chain stopped (a lost task), up
262
+ to 200 per run. When pretix runs without Celery workers, they run the checks themselves, as
263
+ often as cron runs them: those that are due, the longest due first, 20 at most and for about a
264
+ minute per run. Payments are then confirmed later.
265
+
266
+ An invoice whose final status is still unknown after 90 days (an on-chain payment made in time,
267
+ still unconfirmed on a congested network) is no longer checked; it is logged on its order, whose
268
+ payment stays pending, the order keeping it: check it in the sattle.me app and settle it in pretix
269
+ by hand (confirm the payment, or cancel it).
270
+
271
+ If pretix confirms a payment but fails to mark its order paid (a plugin reacting to the payment
272
+ fails, the database goes away), the next check marks it paid, as pretix's backend would.
273
+
274
+ ## Security
275
+
276
+ - **The integration key** is stored in pretix's settings store, in its database, like the keys of
277
+ pretix's own payment providers: pretix does not encrypt it there. Once saved, it never goes back
278
+ to the browser (the form shows `*****`, and a key refused is not sent back either), and the
279
+ plugin hides it from the entry pretix writes in its log when the settings are saved. It never
280
+ goes in a log, an exception or a page of the plugin; the SDK never puts it, or a key derived
281
+ from it, in a message or a representation.
282
+ - **One key, one shop.** Create an integration for your pretix shop, and use its key nowhere else.
283
+ If it leaks, remove the integration in the sattle.me app and create a new one: the key can
284
+ make invoices that pay you, never spend your funds. Once it is removed, the old key makes no
285
+ invoice, and the checks of the payments still pending find a Lightning invoice's payment, but
286
+ fail for an invoice with a deposit address ("the integration was removed in the sattle.me
287
+ app", in the payment's details) unless its Lightning invoice was paid: settle those in pretix
288
+ by hand, from what the sattle.me app shows (the SDK's
289
+ [The key is a secret](https://github.com/sattleme/checkout-python#the-key-is-a-secret)).
290
+ - **Payment links** carry a secret of the order tagged for this plugin (as pretix's own payment
291
+ plugins do), compared in constant time: an order's code, or a link of another plugin, never
292
+ opens them. Like the order's own link, a payment link opens the order: it is the customer's.
293
+ The pages are `noindex` and never cached, and use no inline script (pretix's Content Security
294
+ Policy). Nothing the browser sends decides an amount, a currency, a reference or a status.
295
+ - **Outbound requests.** The SDK connects to hosts the merchant chooses (its relays, its Lightning
296
+ address, its Bitcoin node). It refuses IP addresses and `localhost`, follows no redirects and
297
+ checks TLS, but for the merchant's Bitcoin node, which its app may name by an IPv4 address,
298
+ and in plain HTTP for a host of a local network (never `localhost`): the SDK then sends it GET
299
+ requests of mempool.space's API, with nothing but deposit addresses. A name may also lead to an
300
+ address of your own network. So if your pretix server sits in a network with services of its
301
+ own, or holds the keys of several merchants (events of different organizers, each with its
302
+ key), restrict what it can reach to public addresses: a merchant's node on your network is then
303
+ unreachable, and its fallback applies (see the SDK's
304
+ [Outbound requests](https://github.com/sattleme/checkout-python#what-goes-where) and
305
+ [The merchant's Bitcoin node](https://github.com/sattleme/checkout-python#the-merchants-bitcoin-node)).
306
+ - Report a vulnerability privately: see [SECURITY.md](SECURITY.md).
307
+
308
+ ## Privacy
309
+
310
+ - **What the plugin stores**, in pretix's database: each payment's invoice as the SDK made it (its
311
+ reference, amounts in sats and in the event's currency, exchange rate, Lightning invoice and,
312
+ from 1,000 sats, a deposit address of the merchant's wallet) and what its checks found (its
313
+ state, what came, the confirmations, the transactions, the proof of payment). No name and no
314
+ email address: the customer's are pretix's own.
315
+ - **What the pretix server sends**, and to whom (the SDK's
316
+ [What goes where](https://github.com/sattleme/checkout-python#what-goes-where)):
317
+ - the merchant's **Nostr relays**, encrypted for the merchant (NIP-44): each invoice, with its
318
+ price and its note (the event's name and the order's code), which the merchant's app shows;
319
+ - the merchant's **Lightning address** (breez.tips for a sattle.me account): asked for each
320
+ invoice, its amount and, when the address accepts comments, its note, then for its payment;
321
+ - the **rate sources**, one at a time until one answers: asked for the price of bitcoin;
322
+ - the **explorer**, for an invoice with an address: **mempool.space**, or the merchant's own
323
+ **Bitcoin node** when the merchant's app names one (and mempool.space when the node does not
324
+ answer, unless the merchant chose no fallback): the address and its transactions;
325
+ **api.blockcypher.com**: a transaction, only for one no check saw in time.
326
+
327
+ Each of them sees the pretix server's IP address, never the customer's: the customer's browser
328
+ talks to the shop only (the payment page loads nothing from elsewhere).
329
+ - **Removing personal data.** pretix's data shredder « Payment information » (once the event is
330
+ over and its shop offline) also removes what leads to the customer's coins on the blockchain:
331
+ the deposit address and the transactions, from the payments' information, from pretix's log
332
+ entries of them and from their invoices. Their references, amounts, exchange rates, dates and
333
+ states stay, for the organizer's accounting; so do their Lightning invoices, which name the
334
+ merchant's node, never the customer's. An invoice still being checked then (an on-chain
335
+ payment being confirmed) loses them once final. What the merchant's relays received stays
336
+ theirs: the merchant's app keeps its sales.
337
+
338
+ ## Known limits
339
+
340
+ - **No proxy.** The SDK's connections do not use the environment's proxy settings: the pretix
341
+ server needs direct outbound connections.
342
+ - **Currencies.** The method is offered only for a price the SDK takes
343
+ ([Configuration](#configuration)). Its rate sources must price the event's currency too: a
344
+ currency none of them prices, or an amount out of the merchant's limits (the bounds in sats of
345
+ its Lightning address), is refused when the order is placed, with a message, and the customer
346
+ chooses another method. So is the rest of an order that a gift card paid in part, when the
347
+ SDK prices its currency in whole units and that rest is not a whole amount: pretix asks a
348
+ payment method whether it is offered for the order's total, not for that rest.
349
+ - **Confirmations.** An on-chain payment is paid at 3 confirmations on the explorer (mempool.space,
350
+ or the merchant's Bitcoin node), about 30 minutes: the order stays pending until then.
351
+ - **The merchant's Bitcoin node.** A node the merchant's app names on the merchant's own network
352
+ (`http://192.168.1.10:3006`, `http://umbrel.local`) is reachable only by a pretix server on that
353
+ network. Any other server fails every read of it, and its fallback applies: mempool.space, or,
354
+ when the merchant chose none, no deposit address until the node answers (invoices in Lightning
355
+ only; "We could not create your Bitcoin invoice right now" for an amount that can only be paid
356
+ on-chain), and the checks of an invoice with an address fail meanwhile, its payment staying
357
+ pending (never failed for want of an answer).
358
+ - **Time.** Making an invoice runs in the web request of the order, bounded at 20 seconds, after
359
+ 5 at most waiting for another request on the same payment (gunicorn stops a worker after 30
360
+ seconds by default); it never checks a payment too. Checks run in Celery, but for one a
361
+ customer without JavaScript asks for, and all of them on an installation without Celery
362
+ workers: those run in the request, or in pretix's periodic tasks, bounded at 20 seconds each
363
+ (and at about a minute in all per run of the periodic tasks). An order less than 500 seconds
364
+ before its deadline can no longer be paid with Bitcoin: the shortest invoice (a minute), its
365
+ grace period, the time to make it and 5 minutes for its last checks.
366
+ - **An underpayment accepted in the app, read late.** When the merchant accepts in the app what an
367
+ order underpaid on-chain received, and a relay that holds that acceptance does not answer the
368
+ check made after the invoice's end, that check reads the invoice as ended underpaid, which the
369
+ plugin takes as final: the order's payment stays pending with what came noted, as for any
370
+ invoice that ends underpaid, and the plugin does not check it again. The merchant then settles
371
+ the order by hand, as the specification says (SPEC.md §3).
372
+ - **Deposit addresses.** Each invoice of 1,000 sats or more may lease an address of the
373
+ integration's lot for its time: many orders left unpaid at once can empty it, the next ones are
374
+ then payable in Lightning only until the merchant opens the app (see the SDK).
375
+
376
+ ## Troubleshooting
377
+
378
+ The payment's details (in the order, in pretix's backend) and the order's history say what went
379
+ wrong, in plain words; pretix's log (the loggers `pretix_sattleme.*`) says it too, without the key.
380
+
381
+ - **The key is refused when saving the settings.**
382
+ - "This is not the secret key of a sattle.me integration": copy the whole key from the app,
383
+ `sattleme_ck_` included.
384
+ - "This integration was removed in the sattle.me app": create a new integration, and enter its
385
+ key.
386
+ - "This integration could not be found": the merchant's relays do not hold it (yet): open the
387
+ sattle.me app, check the key, and try again.
388
+ - "This integration needs a newer version of the sattle.me plugin": update the plugin.
389
+ - "This key could not be verified": the pretix server could not reach the merchant's relays or
390
+ its Lightning address. Check its outbound connections ([Requirements](#requirements)): direct,
391
+ without a proxy.
392
+ - **"Bitcoin payments are not available right now"** at checkout: the order's history says why
393
+ ("No Bitcoin invoice could be created (…)"): an integration key no longer valid or removed, the
394
+ integration not found on its relays, the merchant's Lightning address answering wrongly, or a
395
+ clock that is off (the pretix server's: keep it synchronized).
396
+ - **"We could not create your Bitcoin invoice right now"**: the relays, the Lightning address or
397
+ the rate sources did not answer in time, or the amount can only be paid on-chain and no deposit
398
+ address of the integration was free (the merchant opens the app to give it more) or the
399
+ merchant's Bitcoin node, without a fallback, did not answer. The customer tries again; it goes
400
+ on: check the server's outbound connections, the node's included
401
+ ([The merchant's Bitcoin node](#known-limits)).
402
+ - **"This order cannot be paid with Bitcoin"**: the SDK refused the amount or the currency
403
+ ([Known limits](#known-limits)).
404
+ - **A payment stays pending.** The payment's details show its last check and its next one. No
405
+ check at all: pretix's periodic tasks (cron) and its Celery workers must run. An on-chain
406
+ payment waits for 3 confirmations, about 30 minutes, longer with a low fee. Checks that fail
407
+ because "a blockchain explorer did not answer", again and again, for an invoice with an
408
+ address: the merchant's app may name a Bitcoin node without a fallback that this server cannot
409
+ reach ([The merchant's Bitcoin node](#known-limits)). "its checks
410
+ stopped: no final status after 90 days": check the payment in the sattle.me app, and settle it
411
+ in pretix by hand.
412
+ - **"The Bitcoin invoice ended underpaid"** in the order's history: less than the amount came,
413
+ and reached the wallet; the payment stays pending. Settle the difference with the customer,
414
+ then confirm the payment by hand, or cancel it for them to pay again.
415
+ - **A customer paid after the invoice ended**: the page says it expired unpaid, as the SDK reports
416
+ it (see [Late payments](#payments-and-orders)): the bitcoin reached the wallet, and pays no
417
+ order. Settle it with the customer by hand.
418
+ - **"… while the order owes … now"** in the order's history, the payment pending: the order
419
+ changed after its invoice was made, then the invoice was paid. Settle the difference with the
420
+ customer, then confirm the payment by hand in the order (or cancel it).
421
+ - **The payment page has no style, or the plugin no icon**: its static files were not collected
422
+ (`python -m pretix rebuild`, or `make production` in a Docker image, after installing it).
423
+
424
+ ## Development
425
+
426
+ The tools, pretix and the SDK come from `uv.lock`, with [uv](https://docs.astral.sh/uv/) 0.13.8
427
+ (`.github/ci-requirements.txt`):
428
+
429
+ ```shell
430
+ uv sync --locked --group test --group pretix-2026-9 # or pretix-2026-7, pretix-2026-8
431
+ uv run --locked --no-sync python scripts/translations.py compile
432
+ uv run --locked --no-sync python -m pytest tests -m "not postgresql" # SQLite
433
+ ```
434
+
435
+ - **The tests** never reach the network: the plugin makes every client of the SDK in one place,
436
+ `pretix_sattleme.sdk.new_client`, where the tests replace the client with a fake once the real
437
+ SDK has checked the key and the options. The tests of PostgreSQL's row locks (marked
438
+ `postgresql`) need PostgreSQL: they fail on another database, never skip. With a pretix
439
+ configuration file whose `[database]` is a PostgreSQL one,
440
+ `PRETIX_CONFIG_FILE=/path/to/pretix.cfg GITHUB_WORKFLOW=local uv run --locked --no-sync python
441
+ -m pytest tests` runs them all, on pretix's migrations. `python scripts/postgres.py start <dir>`
442
+ starts such a server and writes its configuration file, without Docker nor root (Linux x86_64,
443
+ as a user other than root; `stop <dir>` stops it), as the CI does.
444
+ - **The checks**, as the CI runs them: `uv sync --locked --no-install-project --group test`, then
445
+ `black --check .`, `isort --check-only .`, `flake8 .` (pretix's coding standard, with
446
+ pep8-naming), `mypy` (strict), `check-manifest --no-build-isolation`, `python -m build
447
+ --no-isolation --outdir dist .` and `python scripts/check_dist.py dist`, each with
448
+ `uv run --locked --no-sync`.
449
+ - **The end-to-end test**, with Docker: `e2e/run.sh [--celery] [image]` builds the wheels,
450
+ installs the plugin with pip into pretix's own image (`pretix/standalone`, pinned by its digest:
451
+ 2026.9.1's by default), runs it on PostgreSQL, enables the plugin and enters a key in pretix's
452
+ backend, places orders in the shop, checks the payment page, and pays: the payment is checked by
453
+ the page's link for browsers without JavaScript; with `--celery` (pretix's Celery workers, and
454
+ Redis), also by the page's status endpoint through the workers, and by the invoice's background
455
+ checks alone for a customer who left the page. The SDK is replaced there by a fake (`e2e/fake`,
456
+ a test-only plugin installed beside it: the plugin has no switch for it).
457
+ - **The CI** (`.github/workflows/ci.yml`) runs the checks, and the tests on each supported pretix
458
+ and Python version (one job on PostgreSQL, the others on SQLite), and the end-to-end test on
459
+ each supported version's image, with and without Celery, on GitHub-hosted runners.
460
+ - **The translations** (German, informal German, French, Italian): `make localegen` updates the
461
+ catalogs from the code and the templates (GNU gettext's tools, through Django), and
462
+ `make localecompile` compiles them as the build does (`scripts/translations.py`, with Babel:
463
+ the build needs no GNU gettext). `python scripts/translations.py compare` checks that each
464
+ compiled catalog is GNU msgfmt's, byte for byte.
465
+ - **The pinned SDK.** `sattleme-checkout` is a dependency of the package (`>=1.0,<2`):
466
+ installations get it from PyPI. The development and the CI run the copy pinned in `sdk/` (the
467
+ SDK's own files at a commit of [checkout-python](https://github.com/sattleme/checkout-python),
468
+ unchanged, with `sdk/PIN.json`: the commit, the version, each file's SHA-256), through
469
+ `[tool.uv.sources]`; it is never distributed. Beside them, the SDK's vectors of the prices it
470
+ takes (`sdk/spec/vectors/fiat.json`), which the tests run through the plugin's check of a
471
+ price and the SDK's. To take a new version, from a clone of
472
+ checkout-python: `python3 scripts/pin_sdk.py <clone> [<commit>]` (the commit a clean clone is on
473
+ by default), which copies the files of that commit, writes `sdk/PIN.json` and updates `uv.lock`
474
+ (with uv: Python, git and uv are all it needs). It takes only a commit that the clone's `origin`
475
+ has on one of its branches (as last fetched), and says which clone and origin it read. Then
476
+ `uv sync --locked --reinstall-package sattleme-checkout` (with the groups you use): an existing
477
+ environment otherwise keeps the SDK uv built before when `sdk/pyproject.toml` did not change,
478
+ which `tests/test_sdk_pin.py` catches; then the checks and the tests. A new major version
479
+ changes the dependency's range in `pyproject.toml` first.
480
+ - **Dependencies** are locked exactly, with their hashes, never less than 7 days old
481
+ (`exclude-newer`); Dependabot proposes the updates, after the same wait. Dependabot does not
482
+ see the images of the end-to-end test (pretix's and Redis's, pinned by their digests in
483
+ `e2e/run.sh` and the CI) nor PostgreSQL's binaries (pinned by their SHA-256 in
484
+ `scripts/postgres.py`), nor pretix itself, which it is told to ignore (it reads the three
485
+ groups of `pyproject.toml` as one dependency, and would move them all to the newest release).
486
+ pretix is taken by hand: a bugfix release in its group of `pyproject.toml`, then `uv lock`; a
487
+ new feature release as a new group (the oldest one dropped, with `compatibility` in
488
+ `apps.py`), the CI's matrices, its image's digest.
489
+
490
+ ## Releases
491
+
492
+ Releases are the maintainers' only: a maintainer pushes a tag `vX.Y.Z` (the version of
493
+ `pyproject.toml`) on a commit of `main`;
494
+ [`release.yml`](https://github.com/sattleme/checkout-pretix/blob/main/.github/workflows/release.yml)
495
+ runs the CI again, checks the tag, builds the package from the lockfile, and publishes it to PyPI
496
+ by trusted publishing, in the `pypi` environment, once a maintainer approves. The SDK goes first:
497
+ PyPI must have the version of `sattleme-checkout` this plugin needs.
498
+
499
+ **Distribution** is on pretix's marketplace only, which links each plugin to its PyPI project:
500
+ no GitHub release, no other index. Before the first release, PyPI holds a pending trusted
501
+ publisher for `pretix-sattleme` naming this repository, `release.yml` and the environment `pypi`
502
+ (and one for `sattleme-checkout`, in checkout-python), so that no token is stored anywhere. The
503
+ listing, asked for by email while the marketplace's registrations are closed
504
+ (marketplace@pretix.eu), links to this repository, public by then, and to the PyPI project; it
505
+ names the vendor, a support email and a support URL (this repository's issues), and the security
506
+ contact of [SECURITY.md](SECURITY.md). Its overview is this README's introduction, its
507
+ instructions are [Installation](#installation) and [Configuration](#configuration), and say that
508
+ refunds are made by hand ([Payments and orders](#payments-and-orders)). Whether a new release on
509
+ PyPI shows there on its own, the marketplace does not say: check the listing after each one.
510
+
511
+ ## License
512
+
513
+ MIT, see [LICENSE](LICENSE). The sattle.me name and logo
514
+ (`pretix_sattleme/static/pretix_sattleme/sattleme-icon.svg`, the brand's icon, shown in pretix's
515
+ lists of plugins) are not under that license.