openreceive 0.4.27 → 0.4.29

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 (29) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +12 -0
  3. data/lib/openreceive/version.rb +1 -1
  4. data/skills/integrate-openreceive/SKILL.md +18 -1
  5. data/skills/integrate-openreceive/references/astro.md +2 -2
  6. data/skills/integrate-openreceive/references/bolt.md +580 -0
  7. data/skills/integrate-openreceive/references/btcpay.md +1 -1
  8. data/skills/integrate-openreceive/references/django.md +1 -1
  9. data/skills/integrate-openreceive/references/edd.md +407 -0
  10. data/skills/integrate-openreceive/references/fastapi.md +1 -1
  11. data/skills/integrate-openreceive/references/fastify.md +6 -5
  12. data/skills/integrate-openreceive/references/flask.md +1 -1
  13. data/skills/integrate-openreceive/references/fossbilling.md +466 -0
  14. data/skills/integrate-openreceive/references/laravel.md +1 -1
  15. data/skills/integrate-openreceive/references/lovable.md +2 -2
  16. data/skills/integrate-openreceive/references/medusa.md +468 -0
  17. data/skills/integrate-openreceive/references/mobile.md +1 -1
  18. data/skills/integrate-openreceive/references/nestjs.md +3 -3
  19. data/skills/integrate-openreceive/references/next.md +7 -6
  20. data/skills/integrate-openreceive/references/node.md +6 -5
  21. data/skills/integrate-openreceive/references/nuxt.md +2 -2
  22. data/skills/integrate-openreceive/references/paymenter.md +369 -0
  23. data/skills/integrate-openreceive/references/php.md +1 -1
  24. data/skills/integrate-openreceive/references/rails.md +1 -1
  25. data/skills/integrate-openreceive/references/react-router.md +2 -2
  26. data/skills/integrate-openreceive/references/sveltekit.md +2 -2
  27. data/skills/integrate-openreceive/references/tanstack-start.md +2 -2
  28. data/skills/integrate-openreceive/references/woocommerce.md +8 -6
  29. metadata +6 -1
@@ -0,0 +1,466 @@
1
+ This is the full file; follow it from Step 0.
2
+
3
+ # OpenReceive agent directions (FOSSBilling)
4
+
5
+ ```sh
6
+ # READ THIS FIRST: this file is 25 KB and a summary drops required steps. Download it whole:
7
+ curl -fsSL https://openreceive.org/agent-directions/fossbilling/full.md
8
+ # Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
9
+ ```
10
+
11
+ **Step 0 in brief** (Step 0 below has the details):
12
+
13
+ - Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
14
+ - Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
15
+ - The user only pastes codes into this chat. Never ask them to run a command, edit a file or use an admin page.
16
+ - Store each code yourself as Step 2 says. Never put a code in a shell command.
17
+ - Do not suggest rotating or revoking a code because it was pasted here.
18
+ - Setup is done only when the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
19
+
20
+ These directions describe OpenReceive 0.4.29.
21
+
22
+ Install and configure the OpenReceive payment method in the FOSSBilling
23
+ billing panel you are working in. Preserve its theme, clients, products,
24
+ invoices and prices. The extension is a ZIP that bundles the PHP engine and the
25
+ checkout's script: do not install Composer or npm packages into FOSSBilling,
26
+ and do not clone the OpenReceive repository.
27
+
28
+ The one required credential is a receive-only NWC code (Nostr Wallet Connect):
29
+ a string from the merchant's wallet that can create invoices and read their
30
+ status, and cannot spend. A swap provider (an "LSC" code) optionally lets
31
+ clients pay with USDT, USDC, ETH or SOL instead; the provider converts the
32
+ payment to BTC over Lightning in the merchant's connected wallet. Available
33
+ assets and networks depend on the provider.
34
+
35
+ Run every `php` command below in FOSSBilling's folder (the one that holds
36
+ `console.php`), as the web server's user, never as root: a root run can leave
37
+ files in FOSSBilling's `data/` folder that the web server cannot write. With
38
+ FOSSBilling's official Docker image, that is
39
+ `docker compose exec -T -u www-data fossbilling php console.php …` (`-T` passes
40
+ stdin through; use the FOSSBilling service's own name; the container starts in
41
+ `/var/www/html`). On a server, it is `sudo -u www-data php console.php …` with
42
+ the site's own user.
43
+
44
+ ## Step 0 — ask for the two codes, one question at a time
45
+
46
+ Before anything else, check one thing: whether OpenReceive is already
47
+ installed (`php console.php openreceive:doctor`). If the command exists, it
48
+ prints `NWC_URI: set` or `unset` (likewise `LSC_URI_PRIMARY`), never the
49
+ values. A code that is already set is not asked for again; if both are set,
50
+ skip to Step 3.
51
+
52
+ Otherwise your next action is a question to the user. Do not download the
53
+ extension, edit Docker files or search anywhere else before asking it. Do not
54
+ read FOSSBilling's `config.php`, deploy config, container environments or other
55
+ projects looking for a code: a new install has neither code yet.
56
+
57
+ The user never runs a command and never edits a file. They paste each code
58
+ into this chat; you store it. That is the supported path: do not ask them to
59
+ run the save command themselves, and do not tell them to revoke or replace a
60
+ code because it was pasted here. Ask one question per message.
61
+
62
+ 1. **First message — the NWC code, and nothing else.**
63
+
64
+ > To receive payments I need a receive-only wallet code. In Rizful: open
65
+ > the menu, tap NWC, choose Receive-only NWC code, and tap Copy
66
+ > (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would
67
+ > rather run your own wallet, Alby Hub works too: Connections → Add
68
+ > Connection → Read Only. Paste the code here and I will store it.
69
+
70
+ 2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
71
+ ask them to copy the receive-only code again. Otherwise do not repeat it:
72
+ reply only that you have it, then ask the next question. You store it in
73
+ Step 2.
74
+ 3. **Second message — swaps.** If the user asked for stablecoins, USDT, USDC,
75
+ ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"),
76
+ this message IS the walkthrough below: do not skip it, and do not ask yes
77
+ or no first. Otherwise ask whether clients should also be able to pay
78
+ with USDT, USDC, ETH or SOL, then give the walkthrough. The walkthrough:
79
+
80
+ > Go to https://lightning-swap.com, sign in for API keys, create a key, and
81
+ > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste
82
+ > it here and I will store it — or say "Bitcoin only" and I will continue
83
+ > without it.
84
+
85
+ Mention FixedFloat only if they already use it.
86
+ 4. **When they paste it.** If it does not start with
87
+ `lightning+swapconnect://`, ask them to copy it again. Swaps are now on,
88
+ so keep the route back (the swap non-negotiable below).
89
+
90
+ Do not report setup as complete until the NWC code is saved, and the LSC code
91
+ is saved or the user said "Bitcoin only". Never invent a placeholder code.
92
+
93
+ ## Step 1 — install the extension
94
+
95
+ The extension needs 64-bit PHP 8.3+ with GMP and sodium. Check first:
96
+ `php -m` must list both `gmp` and `sodium`. FOSSBilling's official Docker
97
+ image has sodium but not GMP, so with it, build an image that adds GMP:
98
+
99
+ 1. Put a `Dockerfile` next to the Compose file, with the same tag as the
100
+ FOSSBilling service's `image:` line:
101
+
102
+ ```dockerfile
103
+ FROM fossbilling/fossbilling:<tag>
104
+ RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
105
+ && docker-php-ext-install gmp && rm -rf /var/lib/apt/lists/*
106
+ ```
107
+
108
+ 2. In the Compose file, replace that service's `image:` line with `build: .`
109
+ (the folder that holds the Dockerfile). Change nothing else in the file.
110
+ 3. Run `docker compose up -d --build`. FOSSBilling's files and `config.php`
111
+ stay in the service's volume; only PHP changes. Check `php -m` again.
112
+
113
+ On a server without GMP, say which PHP extension is missing and stop:
114
+ installing PHP extensions on the user's server is theirs to decide.
115
+
116
+ The extension is the ZIP attached to this GitHub release. Unzip it in
117
+ FOSSBilling's folder: it adds `modules/Openreceive` and
118
+ `library/Payment/Adapter/OpenReceive`, and changes no FOSSBilling file. Never
119
+ install the GitHub source-code ZIP or a ZIP from an older release. With the
120
+ Docker image, download and unpack it inside the container, as the web user,
121
+ then activate the module:
122
+
123
+ ```sh
124
+ docker compose exec -T -u www-data fossbilling sh -c 'curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.29/openreceive-fossbilling-0.4.29.zip && unzip -oq openreceive-fossbilling-0.4.29.zip && rm openreceive-fossbilling-0.4.29.zip'
125
+ docker compose exec -T -u www-data fossbilling php modules/Openreceive/activate.php
126
+ ```
127
+
128
+ On a server, unpack it in FOSSBilling's folder the same way, make the two
129
+ folders the web user's, and run the same `activate.php`. Activation writes the
130
+ payment gateway's files into `library/Payment/Adapter/OpenReceive` from the
131
+ module's own copy, creates the extension's two tables in FOSSBilling's
132
+ database and its payment gateway, "Bitcoin Lightning", hooks its reconcile
133
+ pass into FOSSBilling's cron, and makes the `openreceive:*` console commands
134
+ appear. The gateway stays off until a wallet code is saved. If `activate.php`
135
+ says that folder holds another gateway, report that and stop.
136
+
137
+ ## Step 2 — store the codes
138
+
139
+ Store each code yourself, one per command, and never as a shell argument:
140
+
141
+ 1. Write the code with your file-editing tool, not a shell command (no
142
+ `echo`, `printf` or heredoc), to a new file outside the FOSSBilling
143
+ folder, such as `/tmp/openreceive-code`.
144
+ 2. Run `php console.php openreceive:configure --nwc-uri=- < /tmp/openreceive-code`.
145
+ In Docker: `docker compose exec -T -u www-data fossbilling php console.php openreceive:configure --nwc-uri=- < /tmp/openreceive-code`.
146
+ For the LSC code, use `--lsc-uri-primary=-`.
147
+ 3. Delete the file (`rm /tmp/openreceive-code`), whether the command passed
148
+ or not.
149
+
150
+ The command asks the wallet first and saves the code, encrypted by
151
+ FOSSBilling, only when the wallet answers as receive-only; a failure saves
152
+ nothing. If it reports spend methods such as `pay_invoice`, ask the user for a
153
+ receive-only code again. Saving the wallet code turns the payment method on;
154
+ saving the swap code renames it to "Bitcoin & stablecoins". Never write a code
155
+ into FOSSBilling's database, `config.php` or any file in the FOSSBilling
156
+ folder yourself.
157
+
158
+ Then run `php console.php openreceive:doctor`. It names any failed check and
159
+ exits nonzero; fix it before going on.
160
+
161
+ ## Step 3 — mint a test invoice, then stop
162
+
163
+ Create a small unpaid test invoice, billed to a test client the command
164
+ creates once (`openreceive-test@example.invalid`, so no real client sees it
165
+ and no email reaches anyone), and mint its Lightning invoice:
166
+
167
+ ```sh
168
+ php console.php openreceive:test-invoice --new
169
+ ```
170
+
171
+ To use an invoice that already exists, pass its id instead of `--new`.
172
+ `test-invoice` goes through the same route as the invoice's payment page. It
173
+ prints the amount in sats, the BOLT11 invoice, the invoice page and the
174
+ methods the payment page offers, each swap asset marked available or followed
175
+ by the reason it is not. That reason is the answer; report it. "Below the
176
+ provider minimum" or "above the provider maximum" is about this invoice's
177
+ amount, not a fault. Only when the reason says the provider is unreachable
178
+ does doctor's "Swap provider" line have more detail. `test-invoice` and
179
+ `doctor` are the whole check.
180
+
181
+ Give the user the invoice page, to open in a browser where they are signed in
182
+ to FOSSBilling's admin area; choosing the payment method there opens the
183
+ checkout on this same invoice. Tell them the test invoice and the test client
184
+ are theirs to delete.
185
+
186
+ You cannot pay the invoice: the code is receive-only. Do not pay, settle or
187
+ mark the invoice paid, and do not look for a way to (a wallet control port, a
188
+ test endpoint, another wallet). If the user wants a real settlement test, they
189
+ pay from the invoice page with their own wallet; afterwards the invoice reads
190
+ paid.
191
+
192
+ Setup ends here. Once doctor is clean and the user has the link, your last
193
+ message starts "Setup is finished" and has at most six short lines: the
194
+ invoice page, the methods the checkout offers (Bitcoin, plus USDT, USDC, ETH
195
+ and SOL when the swap code is saved), and one line of what to look at. Do not
196
+ list each coin's availability, mention a minimum, or say a coin will not work:
197
+ a provider minimum depends on the invoice total, and real invoices will
198
+ differ. Do not list what you changed or what doctor checked. Send nothing
199
+ after it. Do not add containers, services, workers or cron jobs:
200
+ FOSSBilling's own cron job runs the extension's pass. If doctor says
201
+ FOSSBilling's cron has never run, say so in one line of that message.
202
+
203
+ ## Non-negotiables
204
+
205
+ - Never print, log or commit a code, never put one in a shell argument, and
206
+ never write one into source files, `config.php`, the database or browser
207
+ code. Doctor's set/unset is all you report.
208
+ - Do not suggest rotating, revoking or replacing a code because it was pasted
209
+ into this chat; that is the supported path.
210
+ - Work only in this FOSSBilling. Never read or run anything from another
211
+ project or directory on this machine (its `node_modules`, tools or source),
212
+ for any reason. A browser, Playwright, hand-made calls to the checkout's
213
+ routes, database queries and reading the extension's source are not part
214
+ of setup: when doctor or `test-invoice` fails, report its output.
215
+ - Run `php` as the web server's user, never as root.
216
+ - Receive-only NWC is required. Never get past the preflight with a code that
217
+ can spend.
218
+ - The extension owns only its two payment tables in FOSSBilling's database.
219
+ FOSSBilling owns clients, invoices, prices, services and email. Do not add
220
+ an external payment database or custom fulfillment code, and do not edit
221
+ FOSSBilling's own files. The Dockerfile that adds GMP and the one Compose
222
+ line that builds it are the only deployment change.
223
+ - IF SWAPS ARE ON, KEEP THE ROUTE BACK. A deposit that arrives short or late
224
+ becomes refundable, and the client claims it later from the same invoice's
225
+ payment page. Keep the extension installed while swap payments may still
226
+ need a refund. https://openreceive.org/guides/swap-refunds.md
227
+ - A receive-only wallet cannot send refunds. Refund a settled payment manually
228
+ from the wallet.
229
+
230
+ ## Further reading
231
+
232
+ - [FOSSBilling Quickstart](https://openreceive.org/guides/quickstart-fossbilling.md)
233
+ - [Automated Swaps](https://openreceive.org/guides/automated-swaps.md)
234
+ - [Swap Refunds](https://openreceive.org/guides/swap-refunds.md)
235
+ - [Lightning Swap Connect URI](https://openreceive.org/guides/lightning-swap-connect.md)
236
+ - [Security](https://openreceive.org/guides/security.md)
237
+ - [Price Feeds](https://openreceive.org/guides/price-feeds.md)
238
+ - [Payment Safety Upgrade](https://openreceive.org/guides/payment-safety-upgrade.md)
239
+
240
+ ---
241
+
242
+ ## The quickstart, in full
243
+
244
+ Inlined verbatim so this file needs no network access. Steps 0–3 above are the setup and this is their reference: where the two differ, the steps win, and its admin-area screens are only for a FOSSBilling with no shell.
245
+ The page it comes from is https://openreceive.org/guides/quickstart-fossbilling.
246
+
247
+ ## FOSSBilling quickstart
248
+
249
+ [FOSSBilling](https://fossbilling.org) is an open-source billing panel for
250
+ hosting companies and other online services. The OpenReceive extension adds a
251
+ payment method to it: the client pays an invoice with Bitcoin over Lightning,
252
+ straight into your own wallet, on FOSSBilling's own payment page. With a swap
253
+ provider, the same page also takes USDT, USDC, SOL and ETH, which the provider
254
+ converts to BTC over Lightning into the same wallet.
255
+
256
+ FOSSBilling keeps owning clients, invoices, prices and services. The extension
257
+ keeps its payment attempts in two tables of FOSSBilling's own database. When a
258
+ payment settles, it records it the way FOSSBilling's own gateways do: a
259
+ transaction in FOSSBilling's payment log, with the payment hash as its id, and
260
+ the amount on the client's balance, in the same database transaction that
261
+ settles the payment. The balance then pays the invoice, so the invoice turns
262
+ paid and FOSSBilling activates or renews the service and sends its emails as
263
+ it does for any other gateway.
264
+
265
+ Requirements: FOSSBilling 0.8 or later, on 64-bit PHP 8.3 or later with GMP
266
+ and sodium, and FOSSBilling's MySQL or MariaDB database. FOSSBilling's cron
267
+ job must run, as its install guide sets up; the official Docker image runs it
268
+ every five minutes.
269
+
270
+ ### Install the extension
271
+
272
+ Each GitHub release attaches the extension as a ZIP. Unzip it in FOSSBilling's
273
+ folder, the one that holds `console.php`. It adds two folders and changes no
274
+ FOSSBilling file: `modules/Openreceive`, the module (its settings page,
275
+ routes, console commands and cron hook), and
276
+ `library/Payment/Adapter/OpenReceive`, the payment gateway.
277
+
278
+ ```sh
279
+ cd /var/www/fossbilling
280
+ curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.29/openreceive-fossbilling-0.4.29.zip
281
+ unzip -oq openreceive-fossbilling-0.4.29.zip
282
+ rm openreceive-fossbilling-0.4.29.zip
283
+ chown -R www-data:www-data modules/Openreceive library/Payment/Adapter/OpenReceive
284
+ sudo -u www-data php modules/Openreceive/activate.php
285
+ ```
286
+
287
+ Use your own FOSSBilling folder and web server user. `activate.php` activates
288
+ the module the way **Extensions** in the admin area does, and you can use
289
+ either. Activation creates the extension's two tables and its payment
290
+ gateway, "Bitcoin Lightning", and hooks its reconcile pass into FOSSBilling's
291
+ cron. The gateway stays off until a wallet code is saved.
292
+
293
+ The module carries its own copy of the payment gateway and writes it into
294
+ `library/Payment/Adapter/OpenReceive` each time it is activated, so running
295
+ `activate.php` again after an update brings the gateway up to date with the
296
+ module. It replaces only OpenReceive's own gateway files: if that folder holds
297
+ anything else, activation stops and says so.
298
+
299
+ The ZIP already bundles the extension's dependencies and the checkout's
300
+ script, under their own prefixed names, so Composer never runs and nothing in
301
+ FOSSBilling's own `vendor/` changes. The GitHub source-code ZIP is not an
302
+ installable extension.
303
+
304
+ #### The module-only ZIP
305
+
306
+ Each release also attaches `openreceive-fossbilling-module-<version>.zip`:
307
+ the module alone, with its files at the top of the ZIP rather than inside
308
+ `modules/Openreceive`. That is the package FOSSBilling's extension directory
309
+ installs. Its **Install** button unpacks the ZIP into `modules/Openreceive`,
310
+ and activating OpenReceive under **Extensions** then writes the payment
311
+ gateway, as above. Both ZIPs hold the same module.
312
+
313
+ #### FOSSBilling in Docker
314
+
315
+ FOSSBilling's official image has sodium but not GMP. Build your own image on
316
+ top of it: put this `Dockerfile` next to your `compose.yml`, use the same tag
317
+ as your image,
318
+
319
+ ```dockerfile
320
+ FROM fossbilling/fossbilling:0.8.8
321
+ RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
322
+ && docker-php-ext-install gmp && rm -rf /var/lib/apt/lists/*
323
+ ```
324
+
325
+ and in `compose.yml` replace the FOSSBilling service's `image:` line with
326
+ `build: .`, then run `docker compose up -d --build`. FOSSBilling's files,
327
+ its `config.php` and the extension stay in the named volume at
328
+ `/var/www/html`; only PHP changes.
329
+
330
+ Run every command inside the container, in `/var/www/html`, as its web user
331
+ `www-data`. Unpack the release there too:
332
+
333
+ ```sh
334
+ docker compose exec -T -u www-data fossbilling sh -c 'curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.29/openreceive-fossbilling-0.4.29.zip && unzip -oq openreceive-fossbilling-0.4.29.zip && rm openreceive-fossbilling-0.4.29.zip'
335
+ docker compose exec -T -u www-data fossbilling php modules/Openreceive/activate.php
336
+ ```
337
+
338
+ Always pass `-u www-data`. A command that runs as root can leave files in
339
+ FOSSBilling's `data/` folder that the web server cannot write.
340
+
341
+ ### Configure the wallet
342
+
343
+ You need a receive-only NWC code: a Nostr Wallet Connect code that can create
344
+ invoices and read payments but cannot spend. The extension refuses a code that
345
+ can spend.
346
+
347
+ In the admin area, open **Extensions**, then the settings (gear) button on
348
+ **OpenReceive**. Paste the code into **Receive-only NWC code** and save. To
349
+ accept stablecoins too, paste a swap provider code into **Swap provider
350
+ code**. FOSSBilling stores both encrypted with its install's salt, and the page
351
+ never shows them again; it says only whether each is set.
352
+
353
+ From a terminal, pipe each code into `openreceive:configure` from your secret
354
+ manager or a protected file. Never type a code as a command argument:
355
+
356
+ ```sh
357
+ sudo -u www-data php console.php openreceive:configure --nwc-uri=- < /secure/path/wallet-code
358
+ sudo -u www-data php console.php openreceive:configure --lsc-uri-primary=- < /secure/path/swap-code
359
+ sudo -u www-data php console.php openreceive:doctor
360
+ ```
361
+
362
+ The settings page and `configure` both ask the wallet first and save the code
363
+ only when it answers as a receive-only wallet. Saving the wallet code turns
364
+ the payment method on. Saving a swap code renames the default "Bitcoin
365
+ Lightning" to "Bitcoin & stablecoins"; the settings page's name field, or
366
+ `--name="…"`, sets your own. Skip the swap code for Bitcoin-only checkout.
367
+
368
+ `doctor` checks the module, GMP and sodium, each code as set or unset (never
369
+ its value), the payment gateway's files and row, the tables, the checkout's
370
+ files, the wallet,
371
+ the price feed for every FOSSBilling currency, each swap provider and the cron
372
+ hook with FOSSBilling's last cron run. It exits nonzero when a check fails.
373
+
374
+ ### Check it
375
+
376
+ Make a Lightning invoice through the same route the payment page uses, for a
377
+ new $5 test invoice, or for any unpaid invoice by its id:
378
+
379
+ ```sh
380
+ sudo -u www-data php console.php openreceive:test-invoice --new
381
+ sudo -u www-data php console.php openreceive:test-invoice <invoice id>
382
+ ```
383
+
384
+ `--new` bills a test client that it creates once,
385
+ `openreceive-test@example.invalid`, so no real client sees the invoice and no
386
+ email reaches anyone. `--amount=` and `--client=<email>` change what it bills
387
+ and to whom. Delete the test invoice, or the test client, in the admin area
388
+ when you are done.
389
+
390
+ It prints the amount in sats, the Lightning invoice and the invoice page, then
391
+ each method the payment page offers: Bitcoin Lightning, and each swap asset
392
+ with its network and whether it is available for this amount. A small invoice
393
+ is often below a swap provider's minimum; that is the amount, not a fault. The
394
+ invoice page opens in a browser that is signed in to the admin area.
395
+
396
+ ### How a payment works
397
+
398
+ 1. The client picks the OpenReceive method when checking out an order, or on
399
+ an unpaid invoice's page, and FOSSBilling opens its payment page with the
400
+ checkout on it.
401
+ 2. The extension charges the invoice's total with tax, in the invoice's
402
+ currency, converted to sats at the current BTC price. FOSSBilling decides
403
+ who may open the payment page: the client the invoice belongs to, an admin,
404
+ or anyone holding the invoice's link when you allow paying from the link
405
+ (FOSSBilling's own invoice setting). Only that browser session can make or
406
+ follow the invoice's payment.
407
+ 3. Once the wallet reports the payment, the extension records the transaction
408
+ and the client's balance in the same database transaction that settles it.
409
+ Right after, the balance pays the invoice, and FOSSBilling runs its usual
410
+ work, such as activating the service and sending the receipt. Should that
411
+ last step fail, the amount stays on the client's balance, and FOSSBilling's
412
+ cron pays the client's unpaid invoices from it on its next run.
413
+ 4. The checkout returns the client to the invoice, now paid.
414
+
415
+ The checkout asks the wallet while the payment page is open. If the client
416
+ closes it before the payment settles, the extension's pass on FOSSBilling's
417
+ cron finds the payment on the next run. `php console.php openreceive:reconcile`
418
+ runs one pass by hand.
419
+
420
+ A client who leaves and comes back to the invoice gets the same Lightning
421
+ invoice again while it is still valid.
422
+
423
+ Routine lines go to FOSSBilling's `data/log/billing` log. Warnings and errors
424
+ also appear under **Activity** in the admin area.
425
+
426
+ ### Refunds and removal
427
+
428
+ The receive-only wallet cannot send refunds. Send a refund from your own
429
+ wallet, then record it in FOSSBilling. A client whose swap deposit never
430
+ converted reclaims it from the same invoice's payment page, while the invoice
431
+ is still unpaid. If you turn on swaps, you commit to keeping that path
432
+ available. See [swap refunds](https://openreceive.org/guides/swap-refunds.md).
433
+
434
+ Deactivating the module turns its payment gateway off, because a deactivated
435
+ module serves no checkout. Activating it again turns the gateway back on when
436
+ a wallet code is saved.
437
+
438
+ Uninstalling the module keeps the two tables, which are a record of payments
439
+ received, and leaves the gateway off. Its row and its files in
440
+ `library/Payment/Adapter/OpenReceive` stay too, since FOSSBilling's invoices
441
+ and transactions refer to the gateway.
442
+
443
+ ### Tested, and not tested
444
+
445
+ Tested on 2026-10-16 with FOSSBilling 0.8.8's official Docker image with GMP
446
+ added, MariaDB 11.8, a test wallet and a test swap provider: install from the
447
+ built ZIP, `activate.php`, configure from stdin and from the settings page,
448
+ the doctor, and a client ordering a product and paying by Lightning and by
449
+ USDT on Solana in Chromium, after which the invoice reads paid and the
450
+ service is active. A payment whose page was closed was recorded by
451
+ FOSSBilling's cron. Another client, a visitor and a request without the page's
452
+ security token were refused.
453
+
454
+ Tested on 2026-10-18 in the same setup: the module-only ZIP installed through
455
+ FOSSBilling's own **Install** and **Activate** buttons in the admin area, with
456
+ the extension directory's answer for OpenReceive supplied locally, then the
457
+ same checks. Deactivating, activating again, uninstalling, reinstalling and
458
+ updating a 0.4.28 install with `activate.php` were checked too. On
459
+ FOSSBilling 0.8.0, the oldest release the module accepts: the same install
460
+ and activation, `configure`, the doctor, `test-invoice --new`, deactivating
461
+ and activating again.
462
+
463
+ Not tested: FOSSBilling behind nginx rather than its image's Apache, shared
464
+ hosting without a shell, and FOSSBilling's subscription payments. Lightning
465
+ cannot pull a payment, so OpenReceive offers no subscriptions: the client
466
+ pays each renewal invoice.
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/laravel/full.md
17
17
  - Do not suggest rotating or revoking a code because it was pasted here.
18
18
  - Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
19
19
 
20
- These directions describe OpenReceive 0.4.27.
20
+ These directions describe OpenReceive 0.4.29.
21
21
 
22
22
  Add OpenReceive to a Laravel application — the app you are already working in.
23
23
  You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -17,7 +17,7 @@ If your fetch tool gave you a summary, fetch that URL again for the full text.
17
17
  - Do not suggest rotating or revoking a code because it was pasted here.
18
18
  - Start Step 1 only once NWC_URI is saved, and LSC_URI_PRIMARY is saved or the user said "Bitcoin only".
19
19
 
20
- These directions describe OpenReceive 0.4.27.
20
+ These directions describe OpenReceive 0.4.29.
21
21
 
22
22
  Add OpenReceive to this Lovable app: a TanStack Start app on Cloudflare
23
23
  Workers, with Lovable Cloud or a connected Supabase project as its database.
@@ -121,7 +121,7 @@ saved or explicitly declined.
121
121
 
122
122
  ## Step 1 — the packages
123
123
 
124
- Add `@openreceive/http` and `@openreceive/react` at 0.4.27 or newer.
124
+ Add `@openreceive/http` and `@openreceive/react` at 0.4.29 or newer.
125
125
  Nothing else: no `pg`, no Postgres driver, no OpenReceive scaffold. Do not
126
126
  change the Vite or Wrangler configuration.
127
127