This is the full file; follow it from Step 0. # OpenReceive agent directions (Django) ```sh # READ THIS FIRST: this file is 43 KB and a summary drops required steps. Download it whole: curl -fsSL https://openreceive.org/agent-directions/django/full.md # Skip the download only if you already have all of it: pasted, read from disk or fetched raw. ``` **Step 0 in brief** (Step 0 below has the details): - Before installing or editing anything, ask the user for a receive-only NWC code. One question per message. - Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first. - The user only pastes codes into this chat. Never ask them to edit .env or run a command to save one. - Write each code into .env yourself, as Step 0 says. Never echo it or put it in a shell command. - Do not suggest rotating or revoking a code because it was pasted here. - Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only". These directions describe OpenReceive 0.4.19. Add OpenReceive to a Django project — the app you are already working in. You do not need a copy of the OpenReceive source: the Python package is on PyPI (`openreceive[django]`), the frontend packages are on npm (and the package carries the standalone checkout as static files for projects with no bundler), and the quickstart is appended to this file in full, so you can do the whole integration without fetching anything. Prefer the published package and the mounted routes — do not reimplement wallet RPC, settlement, or pricing. Do not clone the OpenReceive repository into this app, and do not copy a demo's models (`ShopOrder`, `ShopUser`, a signed-cookie visitor) over tables that already exist. Find this application's order, product, and user models — whatever they are actually named — and map the three hooks onto those. Keep this application's template layer, its authentication (`django.contrib.auth` and its `User`, allauth, whatever it runs) and its database. Pick the frontend package that matches what already renders here (`@openreceive/elements` — or the packaged static build — for Django templates and HTMX; `/react`, `/vue`, `/svelte` or `/angular` for an existing SPA) — do not add React to a templates-and-HTMX app. Reuse the app's existing `request.user` / session in `authorize`; the shipped migration adds only its own two tables to the app's database, through `manage.py migrate`. Do not add Django REST Framework for these routes: the mount is one `include()`, and the engine owns its own gates. ## What OpenReceive is A payment library that runs inside YOUR server. It mounts HTTP routes in the application you are editing, issues Lightning invoices against a wallet the merchant already controls, and calls back into your code when one settles. There is no OpenReceive account and no API key, and OpenReceive never holds the funds — the sats land in the wallet the merchant connected. The one required credential is a receive-only NWC code (Nostr Wallet Connect): a string from the merchant's wallet that can create invoices and read their status, and cannot spend. A swap provider (an "LSC" code) optionally lets the payer send USDT, USDC, ETH or SOL instead, converted into that same Lightning payment. Step 0 collects those credentials from the user; you write three hooks — `authorize`, `amount_for`, `on_paid` on a `Host` class named in `settings.OPENRECEIVE`; OpenReceive supplies invoices, polling, settlement and the checkout UI. It never owns orders, users, prices, or fulfillment. ## Step 0 — ask for the two codes, one question at a time Before anything else, look at one file: the project's `.env`, if it exists. Read it only far enough to see whether `NWC_URI` and `LSC_URI_PRIMARY` are there and non-empty, and never print the values. A code that is already set is not asked for again; if both are set, skip to step 5 (making the server load the file), then the quickstart. Otherwise your next action is a question to the user. Do not install the package, edit the app, write `.env.example`, or search anywhere else before asking it. Do not read deploy config (compose files, platform secrets), `settings.py` secrets, Docker containers, or process environments, and never run `printenv`. A new shop has neither code yet: hunting for one burns the turn and can leak other secrets into the transcript. Two server-only URIs are needed before the quickstart: - `NWC_URI` — a receive-only Nostr Wallet Connect code, `nostr+walletconnect://…`. Required for Bitcoin. - `LSC_URI_PRIMARY` — a Lightning Swap Connect URI, `lightning+swapconnect://…`. Required for USDT, USDC, ETH and SOL. Skip it only when the user says they want Bitcoin alone. The user never edits an environment file. They paste each code into the chat; you store it. Ask one question per message. 1. **First message — the NWC code, and nothing else.** Ask for it and walk them through getting it: > To receive payments I need a receive-only wallet code. In Rizful: open > the menu, tap NWC, choose Receive-only NWC code, and tap Copy > (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would > rather run your own wallet, Alby Hub works too: Connections → Add > Connection → Read Only. Paste the code here and I will store it. Do not mention `.env`, exports, or "tell me when it's set". 2. **When they paste it.** If it does not start with `nostr+walletconnect://`, ask them to copy the receive-only code again. Otherwise write `NWC_URI=` into the project's `.env`, creating the file if needed. Make sure `.gitignore` covers `.env` (and `.dockerignore`, if the app has one). Never echo the value, commit it, or put it in client code. Reply only that it is saved, then ask the next question. 3. **Second message — swaps.** If the user already asked for stablecoins or altcoins, skip the yes/no and go straight to the walkthrough. Otherwise ask whether payers should also be able to pay with USDT, USDC, ETH or SOL. The walkthrough: > Go to https://lightning-swap.com, sign in for API keys, create a key, and > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste > it here and I will store it — or say "Bitcoin only" and I will continue > without it. Mention FixedFloat only if they already use it. 4. **When they paste it.** If it does not start with `lightning+swapconnect://`, ask them to copy it again. Otherwise add `LSC_URI_PRIMARY=` to the same `.env`, without echoing it. Swaps are now on, so build the refund route back (the swap non-negotiable below) as part of this integration. If they chose Bitcoin only, leave `LSC_URI_PRIMARY` unset and skip that route. 5. **Make the server load the file — yourself.** Django does not read `.env` on its own. If the app already uses `django-environ`, make sure it reads this file; otherwise add it and call `environ.Env.read_env()` in `settings.py` before anything reads the environment. When the app is started with Docker Compose, give the service `env_file: .env`. Restart the server after writing the file. Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot runs the receive-only preflight: if it reports spend methods such as `pay_invoice`, remove `NWC_URI` from `.env` and ask for a receive-only code again. Never set the spend-capable override to get past it. Before the deploy that turns this on, run `OPENRECEIVE_PREFLIGHT=1 manage.py check --deploy`: it runs the receive-only wallet preflight as a system check (`openreceive.E002` on a missing, dead or spend-capable code), because the wallet client is built lazily on the first request rather than in `AppConfig.ready()`. ### Upgrading an existing install This is not the opening move of a new integration. When OpenReceive is ALREADY installed here, `manage.py openreceive_doctor` reports every credential as present or missing (never the value), the wallet preflight, the two tables, the mount, and any hook still on a placeholder; `--offline` skips the relay probe. Check the installed `openreceive` (`pip show openreceive`) and `@openreceive/browser` (or the `MANIFEST.json` beside the packaged static checkout) against the release named at the top of this file: the headless display models below do not exist in older versions, and the first tile click throws with nothing saying why. Upgrade first — and if this app runs in containers, rebuild the images: the package is baked into the image, so an in-place `pip install -U` is undone by the next `compose up`. Only then start the quickstart. ## After the quickstart — hand over, then stop The quickstart is done when `python manage.py openreceive_doctor` is clean and this app serves the checkout page for one of its orders. Doctor names any failed check and exits nonzero; fix it before going on. Give the user that checkout link. The browser check in the quickstart's "Render the checkout" section (payment-method icons, wallet logos, a pay tutorial) is theirs: tell them what to look at, and do not run it yourself. You cannot pay the invoice: the code is receive-only. Do not pay, settle or mark an order paid, and do not look for a way to (a wallet control port, a test endpoint, another wallet). If the user wants a real settlement test, they pay on that link from their own wallet, and `on_paid` marks the order paid. Setup ends here. Say "Setup is finished" in one message, with the link and what to check. Do not offer more work or end the message on a question. ## Non-negotiables The quickstart below has the code. These are the rules it cannot state for itself, and they hold for every integration. - OpenReceive never owns orders, users, prices, or fulfillment. The section below is how those tables sit next to the engine — not a second order model, and not an association to `OpenReceivePayment`. - Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code, logs, or assets. - Do not suggest rotating, revoking or replacing a code because it was pasted into this chat; that is the supported path. - Work only in this application. Never read or run anything from another project on this machine (its `node_modules`, tools or source), for any reason. A browser and Playwright are not part of setup. - The host owns the price. `amount_for` reads it from your own data; reject payer-supplied amounts. - `authorize` runs on every request, and the `resource` it receives is a CLAIM the payer made, not proof. Read the framework session; never trust a body field. `openreceive_install` writes `authorize = staticmethod(ALLOW_ALL_AUTHORIZE)`, a placeholder that allows everything (`manage.py check` warns `openreceive.W002` while it is set) — replace it with this app's real ownership check, same as `on_paid`. - `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one per thing you fulfill, created before checkout, kept across retries, never reused. A fresh id per page load lets one order be paid twice. - Receive-only NWC is required; a spend-capable code fails closed at boot unless explicitly overridden. - There is NO merchant-initiated refund of a settled Lightning payment, because the wallet cannot spend. Swap refunds — a payer reclaiming a deposit that never converted — are the only refund OpenReceive performs, and only from the `refund_required` provider state. Do not build, promise, or imply a Lightning refund path. - IF YOU TURN SWAPS ON, BUILD THE ROUTE BACK. A deposit that arrives short or late becomes `refund_required`, and the payer claims it on a SECOND VISIT, after leaving your page to fetch an address from another wallet. Three things must exist or that money is unreachable through your UI: a per-order URL your server serves (`/checkout/:reference` — `syncUrl` on ``, `sync-url` or `resumable` on ``), your own order-summary route to restore the order from, and the ATTEMPT. `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the reference alone opens on the method grid. Re-picking the same coin (`POST /swaps`) re-serves the committed attempt — but only while it is live, and the shadow invoice behind a swap lasts about half an hour, after which the same click mints a NEW deposit address and the refund is off-screen. Keep the `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on ``; the `resume-payment-hash` attribute, fed from the `openreceive-state` event (`event.detail.state.payment_hash`), on ``. https://openreceive.org/guides/swap-refunds.md - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside the price from `amount_for` and both drop-ins render it above the amount. Without it the checkout is a QR and "$1.00" with no sign of what the dollar is for. - Show the payer the transaction record: `createTransactionDetails(...)` rows, collapsed behind a caret, on the live checkout AND on the receipt. A payment hash and a deposit txid are the only evidence a payer has that they paid you. `` / React's `` already render this panel and the `description` — these two rules cost you code only on a custom UI or your own receipt page, never a reason to replace the drop-in. (It returns no rows while the rail is `checkout_lock` — before the payer has chosen anything there is no transaction — so render the caret only when the rows are non-empty.) - HTTP JSON is snake_case; the browser packages' TypeScript APIs are camelCase. - Money is integers or decimal strings — never binary floats. ## Your tables, not ours The shipped migration adds `openreceive_payments` and `openreceive_meta` to THIS application's database when you run `manage.py migrate`. That is the whole persistence OpenReceive needs. It does not replace your orders, users, or products, and you do not join them. - **Find this app's models first.** They may be named `Order`, `Invoice`, `Booking`, `Product`, `Variant`, `User`, `Account` — anything. Wire the hooks to those. Do not generate a parallel `ShopOrder` / `ShopProduct` / `ShopUser` stack, and do not add a new app for them. - **The payable row's id is the `reference`.** Create it before checkout, keep it across retries, never reuse it. Pass that id to ``. A fresh id per page load lets one order be paid twice. - **Products (or the catalog) are the price authority.** Order creation reads live prices into the order (snapshot line items if this app has them). `amount_for` reads only that order — never a payer-supplied amount, never a live catalog lookup that could re-price a cart already placed. Return `{"currency": ..., "value": ...}` with `value` a decimal STRING, plus a `description` of what they are buying. - **Users own the order; OpenReceive never sees them.** `authorize` uses the same ownership check this app already uses on the order detail / pay view — `request.user`, `request.session`, a signed cookie, whatever it is. Keep Django's auth and its `User` model; `context.request` is the `django.http.HttpRequest`, so `request.user` is right there. `context.resource["reference"]` is a claim the payer sent, not proof. - **The order is unpaid or paid.** Do not copy `pending` / `expired` / `failed` / `attention` onto it. Those are attempt statuses on `openreceive_payments`. An expired invoice does not cancel the order; a later checkout may mint another attempt. The engine refuses a new checkout under a reference that already settled (409). - **Do not relate to `OpenReceivePayment`.** No `ForeignKey`, no `OneToOne`, no `ManyToMany` either direction, and no admin `inline` on it. `reference` is not unique (many attempts per order). Fulfillment is a guarded transition on YOUR order row inside `on_paid` — `Order.objects.filter(pk=…, state="awaiting_payment").update(…)` (or this app's equivalent). Database writes only in the hook; emails, jobs, and channel broadcasts in `after_paid` or after commit. - **Do not wrap the mounted routes in Django REST Framework.** `include("openreceive.django.urls")` is the whole mount; DRF authentication classes, renderers and permission classes would sit in front of the engine's own JSON-only, same-site and authorize gates and change the wire contract. Your DRF views stay yours. ## If you build your own checkout UI The engine serves JSON only, so the view is yours — but the drop-ins (``, React's ``) already obey all of this. This list is the short form of https://openreceive.org/guides/checkout-ux.md, for a UI built on `@openreceive/browser/headless`. Read that before writing components. - Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the Lightning invoice, then restore the same bolt11 without another mint. - `createCheckoutController` is the engine. Do not hand-roll a poll loop. - `createCheckoutStatusModel` for the status line. Do not draw a Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's. - `resolveWizardSelection` decides whether to ask "which network?". A one-network asset starts the swap from the tile. Key `selectedAssetByGroup` by group (`USDT`), valued by `pay_in_asset` (`USDT_TRON`). - `createMethodGridDisplay` for tiles, including `limitMessage` so an unavailable method says the minimum in the payer's currency. - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo, and the bare amount each get a copy row. Render `swap.networkWarning*` as the model gives it. - `swap.deposit_amount` is the only amount a payer is told to send. Never put a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount: "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to send. The one fiat figure on a USDT/USDC deposit panel is the cart total (`payout_fiat`); express "you send" and the fee in the token. Use `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and it applies this for you; SOL and ETH keep a fiat breakdown. - `createCheckoutSession` owns mint and swap start. To start swaps, pass its `swap` option (`selection`, `prefix`, `fetch`) together. Without it `startSwap` reports through `onError`. - `createQrSvg` is async. Use `createQrSvgController` so you do not render `[object Promise]`. - `checkoutLabels` for every payer-facing string. Only write copy it lacks. - `stageSwapRefund` then `confirmSwapRefund` — only the second submits. Validate with `getSwapRefundFormError`. Treat `409` as a normal outcome. - Pass `{ resumable: true }` to `createSwapDisplayModel` when the payer has a URL they can come back to, and render `display.refundReturnLabel`. Resume helpers (`createGuestCheckoutResume`, `createGuestOrderFetcher`) are on `@openreceive/browser`, not `/headless`. - A refund replaces the deposit panel. On `refund_required` also drop "switch payment method". - No "Open wallet" button on desktop. - Wallet suggestions: `getPaymentWizardRoutes()` + `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial images load from a JavaScript chunk. For a custom headless UI, load it when a tutorial opens and look up the returned table by the tutorial's `path`: ```js import { loadPayTutorialImages } from "@openreceive/browser/headless"; const images = await loadPayTutorialImages(); const src = images[tutorial.path]; // data URI for the selected tutorial ``` Render `src` as the image source and update your UI after loading. Existing display objects do not update: their `tutorial.image` stays `undefined` if created before loading. Alternatively, await the loader, recreate the displays with `createWizardRouteDisplays`, and render the new `tutorial.image`. Show the caption while loading or if loading fails; never use an empty image source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`. For missing images, check CSP errors, failed chunks, and stale displays. Registry paths are lookup keys; there is no asset option or image route. The registry answers ~37 wallets: pass `providerPreviewLimit` and build "show all" from `display.providerCount`, or they push the QR off the screen. ## More documentation Fetch one when the moment comes. Each is raw markdown, so a plain GET is enough; drop the `.md` for the same page a person would read. - https://openreceive.org/guides/authorization.md — before you write `authorize` - https://openreceive.org/guides/environment-variables.md — every variable, and what is deliberately not one - https://openreceive.org/guides/storage.md — the engine tables and the attempt state machine - https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, attributes and slots - https://openreceive.org/guides/checkout-ux.md — read before building any custom UI - https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds - https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay tutorials come from: inside the JavaScript, nothing to serve. This is the page that owns the image rule, not the summary in checkout-ux.md - https://openreceive.org/guides/automated-swaps.md — only if `LSC_URI_PRIMARY` is set - https://openreceive.org/guides/swap-refunds.md — the refund flow, and the route back to it. Read it before you turn swaps on - https://openreceive.org/guides/lightning-swap-connect.md — what an `LSC_URI_*` code actually is - https://openreceive.org/guides/price-feeds.md — where the fiat→sats rate comes from, and how to replace it - https://openreceive.org/guides/host-testing.md — testing your three hooks without a live wallet or provider - https://openreceive.org/guides/rate-limiting.md — before a public shop goes live - https://openreceive.org/guides/security.md and https://openreceive.org/guides/deploying.md — before this goes anywhere real - https://openreceive.org/guides/api-reference.md — every route, option and error code - https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the mounted engine's routes with your own - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library - https://openreceive.org/guides/flask-recipe.md — the same engine as a Flask Blueprint, if this app is Flask after all - https://openreceive.org/guides.md — the index, if what you need is not above Questions, or a problem with the library itself: https://openreceive.org/contact - https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts --- ## The quickstart, in full Inlined verbatim so this file needs no network access — follow it once Step 0 passes. The page it comes from is https://openreceive.org/guides/quickstart-django. ## Django quickstart Requires Python ≥ 3.10 and Django ≥ 5.2 (PostgreSQL, SQLite or MySQL). Install the Python package with the Django extra: ```sh pip install "openreceive[django]" ``` That is the whole install. `openreceive[django]` brings Django. The base package brings the wallet client (websockets, coincurve, cryptography), the HTTP engine and the `openreceive` CLI. Use `uv` or a virtualenv on Python 3.10 or newer. A system Python 3.9 cannot install it. If your app brings its own NWC client, set `OPENRECEIVE["SERVICE"]` instead (see below). Then add the app, point it at a host class, and mount the routes: ```python # settings.py INSTALLED_APPS += ["openreceive.django"] OPENRECEIVE = { "HOST": "shop.openreceive_host.Host", # the class with the three hooks (generated below) "PRICE_CURRENCIES": ["USD"], "RATE_LIMITING": False, # True for public web shops (see below) "OPPORTUNISTIC_RECONCILE": True, # or {"min_interval_seconds": …}; False only with your own worker "DATABASE": "default", # the DATABASES alias that holds the two engine tables } ``` ```python # urls.py from django.urls import include, path urlpatterns += [path("openreceive/", include("openreceive.django.urls"))] ``` `HOST` is a dotted path, not a callable. That keeps it cache-safe and friendly to `manage.py check`, like the `AUTH_USER_MODEL` setting. Then run: ```sh manage.py openreceive_install shop # writes shop/openreceive_host.py, prints the lines above manage.py migrate # creates openreceive_payments and openreceive_meta ``` `openreceive_install` writes one file, `/openreceive_host.py`. It holds the three hooks with the generated placeholders wired in, and the exactly-once fulfillment note as comments. The command then prints the settings and urls lines to add. It never edits `settings.py` or `urls.py`. The migration ships inside the `openreceive.django` app, so `manage.py migrate` applies it alongside your own. It adapts to the configured database backend. The engine owns the `OpenReceivePayment` model, so no model file is generated. The migration adds only the engine's two tables to your database. The engine owns the table's commit locking, write-once settlement, and reconciliation state machine. `reference` is indexed but not unique, because one reference may have many historical attempts. `payment_hash` is globally unique. On SQLite, give the database `OPTIONS = {"transaction_mode": "IMMEDIATE"}` (Django ≥ 5.1). Then two concurrent commits for one order wait on the busy timeout instead of failing with "database is locked" ([Payment storage](https://openreceive.org/guides/storage.md)). #### Fulfill exactly once Within OpenReceive's own settlement paths, `on_paid` runs at most once per reference. If a second invoice for the same reference is paid, OpenReceive records that payment with `status_reason = "duplicate_settlement"` and does not fulfill again. One case is yours to handle. **If anything other than OpenReceive can also fulfill an order**, such as an admin action, a second payment processor, or a replayed job, those paths race each other. Then `on_paid` must be idempotent. The generated host module explains this and shows the guarded transition: ```python def on_paid(self, settlement: PaymentSettlement) -> None: claimed = Order.objects.filter(pk=settlement.reference, state="awaiting_payment").update( state="paid", paid_at=datetime.fromtimestamp(settlement.paid_at, tz=UTC) ) if claimed == 0: return # someone else already fulfilled it # FulfillOrder — like Order — is your own application code: ship the goods, # enqueue the confirmation email. OpenReceive provides neither. FulfillOrder.run(settlement.reference, payment_hash=settlement.payment_hash) ``` Delivery is at-least-once. `on_paid` runs inside the settlement transaction, which the engine wraps in `transaction.atomic()`. If it raises, the transaction rolls back and the next pass retries. So keep `on_paid` to database writes on the order. An email or webhook sent from here would survive the rollback and go out again. The `state="paid"` transition above is the flag. Drain it after commit, either from your own job or from `after_paid`. `after_paid` is the optional fourth method. It runs once, after the settlement transaction commits. **`QuerySet.update()` fires no signals and calls no `save()`.** That is intended. It runs one conditional `UPDATE`, so the claim is atomic and no model code runs between the check and the write. It also means no `post_save` handler runs. That is fine for a job that drains the flag. It does not work for a model whose transition lives in `save()`. If your model owns the transition through signals or an overridden `save()`, take a row lock for the duration instead: ```python def on_paid(self, settlement: PaymentSettlement) -> None: order = ( Order.objects.select_for_update().filter(pk=settlement.reference).first() ) # SELECT … FOR UPDATE if order is None or order.state != "awaiting_payment": return order.state = "paid" order.paid_at = datetime.fromtimestamp(settlement.paid_at, tz=UTC) order.save() # signals fire ``` **Unlocking a download works the same way.** If the payer bought a file, do not unlock it in the browser. Gate the download view on the paid order row, and serve the file only if that row exists: `get_object_or_404(Order, pk=reference, user=request.user, state="paid")`. The `state="paid"` written above is the unlock. The client never decides that an order was fulfilled. It re-reads the row. Buy a Button's `download` view does this in twenty lines. Both shapes are idempotent and correct. They differ only in whether your model layer runs: - `update()` skips the model layer. It is the right default. - The row lock holds the row for the duration of the method. Use it when the transition has to go through your model. On SQLite the lock does nothing, because the transaction itself already lets only one writer run at a time. The generated fulfillment note says the same thing. If your fulfillment is a read-modify-write that one conditional `UPDATE` cannot express, take the lock. Buy a Button (`examples/buttons/server/django`) is a runnable illustration of this boundary. It is not a template to copy models from. It has products, visitors, and orders, and the three hooks are the only bridge. Map that shape onto the models in THIS app. ### Add wallet credentials Put the credentials in the server's environment: ```dotenv NWC_URI= LSC_URI_PRIMARY= LSC_URI_BACKUP= ``` 1. Get a receive-only NWC code from a compatible wallet ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)). Put it in `NWC_URI`. 2. Optional: set up a [swap provider](https://openreceive.org/set_up_swap_provider). Put its connection string in `LSC_URI_PRIMARY`, and a second one in `LSC_URI_BACKUP` if you have one. Never put these values in browser code. Your app refuses to start if the NWC code also advertises spend methods such as `pay_invoice`. Create a receive-only code instead ([Security](https://openreceive.org/guides/security.md)). OpenReceive reads `os.environ`. Django does not load a `.env` file on its own, so something has to put the values there first: `django-environ`, an exported shell environment, or your production secret manager. To allow a spend-capable code explicitly, set `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true`. → [Environment variables](https://openreceive.org/guides/environment-variables.md). ### Configure the host hooks The host class needs three things: authorization, the trusted price, and fulfillment. All three receive the `reference`. This is a string you choose, and it is the fulfillment identity. Use your order id: - one per thing you fulfill, - created before checkout, - kept across retries, - never reused. OpenReceive never looks inside it. But `on_paid` commits fulfillment once per reference, and a new checkout under a reference that already settled is refused with 409. A fresh id per page load would let one order be paid twice. ```python # shop/openreceive_host.py — generated by `manage.py openreceive_install shop`, then filled in. from datetime import UTC, datetime from openreceive.server import HookContext from openreceive.storage import PaymentSettlement from shop.models import Order # YOUR model — it could be named anything. OpenReceive # never sees it or touches its table; these hooks are the # only bridge between the engine and your data. class Host: # Your policy, called before every checkout/payment/swap request. `context` # has three attributes: # context.action — which route: "checkout.prepare", "checkout.create", # "payment.check", "swap.quote", "swap.create", # "swap.read", or "swap.refund" # context.request — the django.http.HttpRequest; read request.user, # request.session or cookies from it, as in a view # context.resource — {"reference": ..., "payment_hash": ...} copied from # the payer's JSON body. It names an order; it does # not prove this caller owns it. reference is always a # validated non-empty str (≤200 chars); payment_hash # is absent except on payment.check / swap.read / # swap.refund. # Return True to allow, False for a 403. Here: only the signed-in customer # who placed the order may act on it. def authorize(self, context: HookContext) -> bool: order = Order.objects.filter(pk=context.resource["reference"]).first() return order is not None and order.user_id == context.request.user.id # The price for a reference — here, your order id — from your own data; # None when there is nothing to pay for (a 404). `value` is a decimal # STRING from the order row, never a float and never a request param. # `description` is what the payer is buying, in your own words. def amount_for(self, reference: str) -> dict | None: order = Order.objects.filter(pk=reference).first() if order is None: return None return { "currency": "USD", "value": str(order.total), "description": f"{order.items.count()} items", } # Runs inside the settlement transaction, only for the order's first settled # attempt. The WHERE clause is the lock: a second fulfillment path of yours # (admin action, replayed job) updates zero rows and does nothing. Plain # ORM calls, because the engine WRAPS this method in transaction.atomic(); # `settlement.connection` is None here. (The SQLAlchemy adapters instead # hand on_paid the transaction's Connection — the one shape difference.) def on_paid(self, settlement: PaymentSettlement) -> None: Order.objects.filter(pk=settlement.reference, state="awaiting_payment").update( state="paid", paid_at=datetime.fromtimestamp(settlement.paid_at, tz=UTC) ) ``` `authorize` receives the Django request that carried the payer's call. So `request.user`, `request.session` and cookies are all available. Keep your project's authentication and its `User`. OpenReceive mints no tokens of its own. The engine reads nothing else from the request. Your policy sees whatever your middleware stack put on it. CSRF stays on. `CsrfViewMiddleware` is yours, and the mounted routes run its check like any other view. A failed check returns the shared `403 FORBIDDEN` JSON error instead of the HTML failure page. To make the check pass: - Render `` in the template that shows the checkout. - Give the element `csrf-header="X-CSRFToken"`. That is the header Django reads. The default is Rails' `X-CSRF-Token`. The checkout client then sends the token from that tag on every request. A view that renders a page with no form normally needs `{% csrf_token %}` or `ensure_csrf_cookie` for the cookie to exist. `{{ csrf_token }}` in the meta tag does that on its own. The generated host module ships two placeholders. Replace both, not just `on_paid`: - `on_paid = staticmethod(LOGGING_ON_PAID)` only logs the settlement and fulfills nothing. Replace it with your real fulfillment (as above). Until you do, orders would be recorded as settled without ever being fulfilled, so `manage.py check` warns (`openreceive.W001`) at every boot. - `authorize = staticmethod(ALLOW_ALL_AUTHORIZE)` allows everything. It treats possession of the reference as authorization, which is safe only while references are unguessable. The check warns (`openreceive.W002`) until you replace it with your own ownership check (as above). A `HOST` that is missing or does not import is `openreceive.E001`. The amount always comes from your own order record. Payer-supplied amounts are rejected. If your app brings its own NWC client, price feed or swap providers, set `OPENRECEIVE["SERVICE"]` to the dotted path of a callable `(env) -> openreceive.server.Service`. Everyone else leaves it out. For public web shops, turn on the per-IP invoice cap with `"RATE_LIMITING": True` (or `{"limit_per_hour": …, "limit_per_day": …}`). Leave it off (the default) when many payers share one IP. The cap counts `REMOTE_ADDR` after your own proxy handling. Behind a reverse proxy, put a trusted-proxy middleware first, or the cap counts the proxy instead of the payer. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md) The wallet client, and its receive-only preflight, is built lazily on the first request. It is never built in `AppConfig.ready()`. That method also runs for `migrate`, `collectstatic` and shells, and a relay probe there would break them on a machine with no relay access. To make a bad `NWC_URI` fail the deploy instead of causing 500 errors for customers, run the preflight as a system check in your deploy pipeline: ```sh OPENRECEIVE_PREFLIGHT=1 manage.py check --deploy # openreceive.E002 on a missing, dead or spend-capable code manage.py openreceive_doctor # the same, for humans; never prints a secret ``` ### Render the checkout Serve the compiled `styles.css` without Tailwind processing. Either import it from JavaScript (with a CSS-capable bundler) or use a plain ``. Do not `@import` it into your Tailwind entry. Its rules have zero specificity, so your own styles can override checkout styles. Scoping does not prevent that. The app serves JSON checkout routes only. Your template does the rendering. Any OpenReceive frontend package works against the `/openreceive` mount. The smallest is the custom element. The Python package carries its standalone build as static files, so a Django template needs no JavaScript bundler at all: ```django {# templates/orders/pay.html #} {% load static %} ``` `openreceive-checkout.js` registers the `` tag when it loads. It is one self-contained ES module with un-minified identifiers. The stylesheet is scoped to what OpenReceive renders. `collectstatic` ships both with the rest of your static files. The package's `MANIFEST.json` names every file and its hash. The element creates the checkout for `reference`, then renders and polls itself. Its default `prefix` is already `/openreceive`. Everything the checkout draws ships inside the JavaScript: the payment-method icons, the wallet logos and the pay tutorials. There is no image file to copy or serve and no asset option to set. Deploy your normal JavaScript and CSS build output, including any generated JavaScript chunks. Bundlers with code splitting can load tutorial screenshots only when a tutorial is first opened. Single-file builds, including the standalone checkout, include them upfront. If your Content-Security-Policy has a strict `img-src`, allow `data:` ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)). Then open the checkout in a browser. Confirm the payment-method icons and wallet logos render, and open a wallet's pay tutorial to check its screenshots. If an image is missing, check the console for CSP violations and the Network panel for failed JavaScript chunks. Allow `data:` in `img-src` and deploy the complete build output. Do not add image routes, copy package source images, or use registry `icon_path` / tutorial `path` keys as browser URLs. If your app has a JavaScript bundler, use the npm packages instead. Either use the same element from `@openreceive/elements` (call `defineElements()` once per page, then use the tag above), or use the matching React, Vue, Svelte, or Angular wrapper with the `csrfHeader="X-CSRFToken"` prop. Both have the same defaults ([Frontend checkout](https://openreceive.org/guides/frontend-checkout.md)). Build a custom checkout only if this app cannot use a drop-in. In that case `@openreceive/browser/headless` is the API ([Headless checkout](https://openreceive.org/guides/headless-checkout.md)). ### Reconciliation Settlement runs on the request path. You do not need a cron job. Disable or tune it with `"OPPORTUNISTIC_RECONCILE"` (`False`, or `{"min_interval_seconds": …}`). Optionally, run one worker so settlement does not wait for the next page load: ```sh manage.py openreceive_notifications ``` The worker listens for NWC-02 `payment_received` notifications. The same process also runs a periodic reconcile pass, every `OPENRECEIVE_NOTIFICATIONS_RECONCILE_INTERVAL_SECONDS` (default 15). That pass catches notifications missed while the worker was down. Run one process in total, not one per web instance. To run a pass yourself, use the one-shot `manage.py openreceive_reconcile`. ### Swap secrets The Python engine recognizes `LSC_URI_PRIMARY` and `LSC_URI_BACKUP`, using the shared [Lightning Swap Connect](https://openreceive.org/guides/lightning-swap-connect.md) vectors. Setting either one auto-builds the matching provider. So an app that wants swaps only supplies the connection strings ([Environment variables](https://openreceive.org/guides/environment-variables.md)). To override this, use `OPENRECEIVE["SERVICE"]`. Build the `Service` with your own providers, or with an empty list to disable swaps. One `openreceive_payments` row holds at most one provider order, in its server-only `swap_data` column. The engine leaves `swap_data` out of the model's `repr`, out of the read-only admin it registers, and out of every public dict. Do not serialize it, log it, or return it from your own API. It may contain a provider credential. **Setting either connection string commits you to refunds.** A swap deposit can arrive short or late. The provider then marks it `refund_required`, and only your UI can claim it. The payer claims it on a second visit, after leaving your page to get an address in another wallet. That needs three things: - a per-order URL your app serves, - a route that restores the order behind it, - something that restores the ATTEMPT, since `/checkouts/prepare` returns none. [Swap refunds](https://openreceive.org/guides/swap-refunds.md) covers all of it. Read it before you set `LSC_URI_PRIMARY`.