This is the full file; follow it from Part 1. # OpenReceive + Stripe agent directions: build card and BTC, USDT & USDC checkout into a new app (Laravel) ```sh # READ THIS FIRST: this file is 60 KB and a summary drops required steps. Download it whole: curl -fsSL https://openreceive.org/agent-directions/stripe/new/laravel/full.md # Skip the download only if you already have all of it: pasted, read from disk or fetched raw. ``` **In brief** (Part 1 has the details): - Build card checkout on Stripe and BTC, USDT & USDC checkout on OpenReceive, on the design in Part 2. - Before installing or editing anything, ask the user for a receive-only NWC code. One question per message. - Next ask for the LSC code, then a Stripe test secret key, then Part 1's question about what is sold. - Never echo a code or key or put one in a shell command. Do not suggest rotating one pasted here. - Part 3's quickstart is not the end: after it, do Part 1 steps 5 and 6, then hand over. Part 3 describes OpenReceive 0.4.23. Parts 1 and 2 are the Stripe design from https://openreceive.org/processors/stripe. # Part 1: build card and BTC, USDT & USDC checkout into this app This app takes no payments yet. You are building both: card payments through Stripe, and BTC, USDT and USDC payments through OpenReceive, on one design that runs in production. Card plans renew monthly. Plans paid in BTC, USDT or USDC are prepaid passes. Credit packs and products cost the same either way. This file has three parts: - **Part 1** (this part): the order of work. - **Part 2**: the design, which says what to build. - **Part 3**: OpenReceive's own directions for this framework, including the full quickstart. Follow it for everything about OpenReceive, with the changes listed in step 4 below. If this app already takes card payments through Stripe, stop and tell the user to use the directions for an existing Stripe app instead: the same URL with `/add/` in place of `/new/`. ## 1. The codes Do Part 3's Step 0 exactly: ask for the receive-only NWC code, then the LSC code, one question per message, and save each one yourself. Then ask for one more, the same way: `STRIPE_SECRET_KEY`, a test-mode secret key (`sk_test_…`) from the Stripe dashboard under Developers → API keys. Save it in the same env file and never echo it. Build and test with the test key only. Going live is the merchant's step, later. ## 2. One question: what this app sells Ask in one message: > What should this app sell by subscription? Give each plan's name, monthly > price, and what it includes (features, or credits per month). Also any credit > packs (credits and price) or one-time products. Or reply "example" for three > plans at $19, $39 and $99 a month (100, 300 and 1,000 credits) and packs of > 100, 300 and 1,000 credits for $15, $39 and $99. Pass prices follow from the answer: 60, 180 and 365 days at 10%, 20% and 26% off the monthly price, rounded to whole dollars. Use those unless the user gives other numbers. ## 3. Read the app (no edits) Find the account or user model, how sign-in works, the database and its migration tool, the frontend (server templates or a SPA), any scheduler or background jobs, and how tests run. ## 4. The OpenReceive quickstart (Part 3), with these changes - **The payable row is the OpenReceive order** from Part 2. Create the orders table first, with Part 2's columns for both payment methods. - **`authorize`, `amount_for` and `on_paid`** follow Part 2's "OpenReceive hooks". `on_paid` calls settle and nothing else. - **Do not hand over after the quickstart.** Part 3's "After the quickstart: hand over, then stop" applies at the end of step 6 below, not here. When the quickstart is done (its doctor check is clean), continue with step 5. ## 5. Build, in this order 1. **Catalog**: plans with their card price, Stripe price ids, pass prices and what they include. Packs and products if sold. Create the Stripe products and prices with a small idempotent setup script (find each by its `lookup_key` before creating it) in test mode, and store the price ids it returns. 2. **Data**: orders, card subscription rows, pass access, pass records, credit lots and the ledger (if credits are sold), and a Stripe webhook event inbox, all from Part 2. 3. **settle** and **the access helper**, from Part 2. Every feature check calls the helper. 4. **Card checkout**: Stripe Checkout sessions in `subscription` mode for plans and `payment` mode for packs and products, with the account id in metadata. Plus a customer portal link for card plans and a success page that only shows a message. 5. **The Stripe webhook**, as in Part 2's "Stripe intake": verify, store, answer 200, process, re-fetch the subscription, settle. Read `STRIPE_WEBHOOK_SECRET` from the environment. Until it is set, the app still boots and the webhook answers 400. 6. **The "Pay with BTC, USDT & USDC" endpoint** and **the checkout page** for one OpenReceive order, reachable from the account. Refuse a pass while a card plan is live, with Part 2's message. 7. **The pricing page and the account page**, as in Part 2. 8. **Expiry**: the sweeper on the app's scheduler, if it has one, and reminder emails if it sends email. ## 6. Check, then hand over - Add tests: settle run twice grants once, extending a pass from `max(now, paid_until)`, a refused pass while a card plan is live, the access helper for card only, pass only, and both, and a webhook with a bad signature getting 400. Run the whole suite. - Ask for the last code, the same way as the others: `STRIPE_WEBHOOK_SECRET` (`whsec_…`). It is shown when a webhook endpoint for this app's URL is added in the Stripe dashboard, or when `stripe listen` runs on the user's own machine. If the user doesn't have it yet, finish without it. Now follow Part 3's "After the quickstart: hand over, then stop", with these changes: - The link is the pricing page. One OpenReceive order for a 60-day pass of the cheapest plan is enough to prove that side. Keep it unpaid. - One of the five lines says card checkout runs in Stripe test mode. - If `STRIPE_WEBHOOK_SECRET` is still missing, name it in one more line, the only line allowed beyond five. --- # Part 2: the design This is the design both modes build. It runs in production next to Stripe. Use this app's own names, ORM, migrations and conventions for everything below. The table and column names here describe roles, not required names. ## The flow ```text Stripe webhook (verified, stored, processed) ──┐ ├──▶ settle(order) ──▶ grant OpenReceive on_paid (inside its transaction) ──┘ ``` Card payments keep coming through Stripe. BTC, USDT and USDC payments come through OpenReceive. Both call ONE settle function. Nothing downstream of settle may care which payment method was used. ## Data **Orders.** One row per purchase, whatever the payment method: - `payment_method`: `card` or `openreceive` - `kind`: `card_plan_period`, `pass`, `credit_pack` or `product` (only the kinds this app sells) - `amount_cents` in the app's currency (USD unless the app already prices in something else), integer cents. Revenue is always fiat, never sats. - `status`: `pending`, then `paid` (plus whatever refund states the app already tracks) - `reference`: for OpenReceive orders, an opaque random string (for example 12 lowercase letters and digits), unique, set when the order is created. Never the row id: ids leak order counts and let anyone guess other checkout URLs. - what was bought: the plan and days for a pass, the pack for a pack, the product or line items for a product - the Stripe ids for card orders (invoice, checkout session, payment intent), each unique If the app already has an orders, payments or purchases table that fits, add these columns to it instead of creating a new one. **Pass access.** At most one live row per account: `account`, `plan`, `paid_until`. It is the prepaid equivalent of a subscription. Keep a record of each pass bought (`account`, `plan`, `days`, `order`, `credits`) for history and support. **Card access** stays where Stripe's subscription state already lives, synced from Stripe webhooks. A row that holds a Stripe subscription id is a card row forever. Only the Stripe sync writes to it. Never write pass access onto it. **Credits**, only if the app sells usage: - One lot per grant: `account`, `source` (card plan, pass, pack, gift), `granted`, `remaining`, `expires_at` (empty means never). - An append-only ledger of grants and spends, each entry with a unique idempotency key. - Spend lots that expire before lots that don't: plan and pass lots first, then packs. Within a group, oldest first. - Lock the account's lots while spending so two requests cannot spend the same credit. ## settle(order) ```text settle(order): in one database transaction: lock the order row if order.status is paid: return # replay, retry or second path mark the order paid case order.kind: card_plan_period → grant the period's credits (key: card plan + period start) pass → extend pass access, grant pass credits (key: pass id) credit_pack → grant pack credits, never expire (key: pack purchase id) product → this app's existing fulfillment after commit: emails, receipts, live updates, background jobs ``` - Every grant writes under a unique key, so a replayed event cannot grant twice even if the order check were bypassed. - OpenReceive runs `on_paid` INSIDE its own settlement transaction. If settle raises, settlement rolls back and OpenReceive retries on its next reconcile pass, so settle must be safe to run again. Anything that leaves the database (email, websocket broadcast, job enqueue) runs only after the outermost transaction commits. ## Prepaid passes - Lengths: 60, 180 and 365 days by default. Show 60 first. A length the merchant doesn't sell has no price; refuse it on the server, so an old browser tab can never create a $0 pass. - Price: card monthly price × days/30 × (1 − discount), rounded to whole dollars. Default discounts: 10% for 60 days, 20% for 180, 26% for 365. Store the pass prices with the plans, separate from Stripe's price ids. A plan sold only as a pass never gets a Stripe price id. - Extend: `paid_until = max(now, paid_until) + days`. The access row takes the plan of the pass just bought, so a higher plan upgrades the remaining time. - Credits: the plan's monthly credits × days/30, rounded, granted at once, expiring at the new `paid_until`. - Never auto-renews. Show "One-time pass, no auto-renew" next to every pass price. Keep the buy button enabled for the customer's current plan, so they can renew early. - A sweeper (the app's scheduler or a periodic job) ends pass access when `paid_until` passes. It never touches card rows. Access checks compare `paid_until` to now, so access ends on time even if the sweeper is late. - If the app sends email: remind 7 days before `paid_until`, and on the day. ## When a customer has both - **A card plan is live** (active, trialing or past due, even if set to cancel at period end): refuse passes, both in the UI (disabled button) and on the server (in the endpoint that creates the OpenReceive order). Copy: "You have a card plan. Prepaid passes become available once it ends. Credit packs are available any time." - **The customer holds a pass, then starts a card plan:** both run. The pass keeps its days. Do not cancel the pass access row when a card plan starts. - **A pass order paid after a card plan started:** settle it normally on the pass access row. Never move it onto the card row. - **Features** come from the single best plan the customer currently has, by card or by pass. Credits add up across both. - **One access helper decides everything:** what plan the account is on and whether it is entitled, from card rows (Stripe status active, trialing or past due) and the pass access row (`paid_until > now`). Every feature check, API gate and limit calls this helper. Route existing scattered checks through it. ## OpenReceive hooks Part 3 explains the hooks. In this design they map like this: - **The payable row is the OpenReceive order.** Create it in the app's own "Pay with BTC, USDT & USDC" endpoint, before the checkout opens. Its `reference` is what the checkout and OpenReceive see. - **`authorize`:** the reference must belong to a pending or paid OpenReceive order owned by the signed-in account. Holding a reference is a claim, not proof. - **`amount_for`:** returns the order's saved `amount_cents` as a decimal string, with a description such as "Plus, 60-day pass". Never a value from the request, never a live catalog lookup, never a float. - **`on_paid`:** finds the OpenReceive order by reference and calls settle. Nothing else. Every "Pay with BTC, USDT & USDC" click may create a new pending order. That is fine. Abandoned pending orders cost nothing. The checkout page for an order must stay reachable from the customer's account (for example `/orders//pay`), because that page is also where a payer claims a swap refund. ## Stripe intake In add mode, check the app's existing Stripe code against these rules and report gaps in your hand-over. Don't rewrite it. In new mode, build it this way. - Verify the webhook signature, store the event under its Stripe event id (unique), answer 200, then process it. Retry failed events. A periodic re-list of recent events catches missed deliveries. - Events: `checkout.session.completed`, `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.paid`. Re-fetch the subscription from Stripe before applying it, because events arrive out of order. - Fulfillment happens only in the webhook, through settle. The success redirect only shows a message. - Card checkout uses Stripe Checkout (`mode: subscription` for plans, `mode: payment` for packs and products) with the account id in metadata. ## The pricing page - Name the second payment method by its coins: "BTC, USDT & USDC". If the app has no swap provider configured (no LSC code), it takes BTC only, so say "BTC" instead everywhere below. - One toggle, "Pay with card" / "Pay with BTC, USDT & USDC", controls the whole plan grid and pack list. Remember the choice per account if the app has accounts. - Card mode shows plans that have Stripe prices. BTC, USDT & USDC mode shows plans that have pass prices. Decide this from the data, not from hard-coded plan names. - Pass plan cards: a 60 / 180 / 365 day switch, the price "/ 60 days", the credits "granted at once", "One-time pass, no auto-renew", and a "Pay with BTC, USDT & USDC" button. - The account page shows how the plan is paid: "Card (renews monthly)" or "Prepaid pass, until ". Card-only buttons such as "Manage payment method" appear only for card plans. ## Never - Never write pass access onto a row that holds a Stripe subscription. - Never fulfill on a redirect, a client callback or a payer-supplied amount. - Never grant without a unique key. - Never change Stripe prices, products, webhook endpoint or API version in an app that already takes card payments. - Never call Stripe from `amount_for` or `on_paid`. --- # Part 3: OpenReceive agent directions (Laravel) **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.23. Add OpenReceive to a Laravel application — the app you are already working in. You do not need a copy of the OpenReceive source: the package is on Packagist (`openreceive/laravel`), the frontend packages are on npm, 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 routes its service provider mounts — 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`, an encrypted-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 view layer, its authentication (Breeze, Fortify, Jetstream, Sanctum, a plain session guard — whatever `Auth` already uses), its Eloquent models and its database. Pick the frontend package that matches what already renders here (`@openreceive/elements` for Blade/Livewire/Inertia-less pages; `/react`, `/vue`, `/svelte` or `/angular` for an existing SPA or Inertia app) — do not add React to a Blade app. Reuse the app's existing `$request->user()` or session in `Host::authorize`; the engine's migration adds only its own two tables to the app's database, through `php artisan migrate`. ## 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`, `amountFor`, `onPaid` on one `App\OpenReceive\Host` class; 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, check one file: the project's `.env`, if it exists. `grep -E '^(NWC_URI|LSC_URI_PRIMARY)=.' .env | cut -d= -f1` names the codes it sets without printing them. Check with that, here and after each write, not by reading the file, 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, Forge/Vapor/Envoyer panels), 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` with your file-editing tool, creating the file if needed. Never write it with a shell command (`echo`, `printf`, a heredoc, `python -c`): the command line shows the code. 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 asked for stablecoins, USDT, USDC, ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"), this message IS the walkthrough below: send it as it is, and do not ask yes or no first. Otherwise ask whether payers should also be able to pay with USDT, USDC, ETH or SOL, then give the walkthrough. 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` with the file-editing tool, never a shell command. 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.** Laravel loads `.env` itself. If the app runs `php artisan config:cache`, run `php artisan config:clear` (or re-cache) after writing the file: a cached config never reads `.env` again. When the app is started with Docker Compose, give the service `env_file: .env`. A Compose variable reaches artisan commands, but not the web server: `php artisan serve` hands requests only what `.env` holds, and php-fpm clears the environment by default. So make the running app read the codes too: keep them in the `.env` the server reads (an image that copies `.env.example` over it drops them), start `php artisan serve` with `--no-reload`, or set `clear_env = no` for php-fpm. 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. ### Upgrading an existing install This is not the opening move of a new integration. When OpenReceive is ALREADY installed here, `php artisan openreceive:doctor` reports every credential as set/unset (never the value), the host class and any placeholder hooks, the route mount, and the wallet preflight. Check the installed `openreceive/laravel` (`composer show openreceive/laravel`) and `@openreceive/browser` 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: `vendor/` is baked into the image, so an in-place `composer update` is undone by the next `compose up`. Only then start the quickstart. ## After the quickstart — hand over, then stop The quickstart is done when `php artisan openreceive:doctor` is clean and this app serves the checkout page for one of its orders. Doctor names any failed check; 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: name it in one line of your closing message, 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 `onPaid` marks the order paid. Setup ends here. Your last message starts "Setup is finished" and has at most five short lines (about 80 characters each): the link, the methods it offers, and one line of what to look at. Send nothing after it. Do not list what changed, copy out the quickstart's browser checklist, offer more work, or end the message on a question. - The link is to a real unpaid order. Keep that order; do not delete it. - When this app's orders belong to a session or cookie, the user's browser cannot open the order you made. Then the link is the shop's own page: "Open and click Buy: it opens the checkout." Do not explain order ownership or mention your test order. - Name the methods it offers: Bitcoin, plus USDT, USDC, ETH and SOL when `LSC_URI_PRIMARY` is saved. Do not mention minimums, and never say a coin will not work or will not be offered. ## 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 Eloquent model over `openreceive_payments`. - 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. - Restart only this app's server, on the port it already uses: stop the process you started, or the one listening on that port, by its pid (or restart its Compose service). Never `pkill` or `killall` by name: that stops other people's servers too. Start it the way this project already does (its README, Procfile, compose file or package script), on its own port, not a port you pick. - Run commands where the app runs. When a compose file builds it, run its package manager, generators, migrations and doctor inside that service (`docker compose exec` or `run`), and rebuild the image after adding a package. This machine's language version and database path are not the app's. - To check that the running app sees the codes, run doctor: it reports each one as present or missing and never prints a value. Never print the environment (`printenv`, `env`, `docker compose config`), even filtered to names. Doctor runs as an artisan command, so also open the checkout page: the web server can miss a code that doctor sees (step 5). - The host owns the price. `amountFor` 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 Illuminate request it is handed — the session, `$request->user()`; never trust a body field. `openreceive:install` scaffolds `use AllowAllAuthorize;`, a placeholder trait that allows everything (the engine warns at boot while it is there) — replace it with this app's real ownership check, same as `onPaid`. - `onPaid` 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 `amountFor` 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 install migration adds `openreceive_payments` and `openreceive_meta` to THIS application's database. 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. - **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). `amountFor` 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 show / pay page — `$request->user()`, a policy, a session key, an encrypted cookie, whatever it is. `$context->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 model `openreceive_payments`.** No Eloquent model, no `hasMany`, no `belongsTo`, no foreign key either direction. `reference` is not unique (many attempts per order). Fulfillment is a guarded transition on YOUR order row inside `onPaid` — `Order::where(...)->where('state', 'awaiting_payment')->update(...)` (or this app's equivalent), with no `DB::transaction()` of your own around it. Database writes only in the hook; emails, jobs, and broadcasts after commit (implement `OpenReceive\Hosts\AfterPaid` for those). ## 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.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-laravel. ## Laravel quickstart Requires PHP ≥ 8.2 (64-bit) and Laravel ≥ 11 (12 current). You also need these PHP extensions: - `ext-gmp`, which is REQUIRED. The NWC transport's elliptic-curve math depends on it. - `sodium` and `mbstring`. - The `pdo_*` driver for your database (`pdo_pgsql`, `pdo_mysql` or `pdo_sqlite`). `php -m` lists what your build has. To add gmp on Debian/Ubuntu, run `apt-get install php8.2-gmp`. The official `php` Docker images do not ship it, and `docker-php-ext-install gmp` alone fails without the GMP headers. Add both to the Dockerfile, before the step that installs the app's Composer packages, and rebuild the image: ```dockerfile RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \ && docker-php-ext-install gmp \ && rm -rf /var/lib/apt/lists/* ``` Run `composer require` with a PHP that has gmp. On a machine without one, use the rebuilt image with the project mounted, then rebuild again so the image installs the new lock: `docker compose run --rm --no-deps -v "$PWD":/app web composer require openreceive/laravel -W`. Never pass `--ignore-platform-req=ext-gmp` or `--ignore-platform-reqs`: Composer then installs a package that fails as soon as it talks to the wallet. Add the Laravel package: ```sh composer require openreceive/laravel -W ``` `-W` lets Composer move Guzzle to 7.x: the wallet client's WebSocket middleware needs Guzzle 7, and a Laravel 13 app can lock Guzzle 8. That is the whole install. `openreceive/laravel` depends on `openreceive/openreceive`, the engine. So the default wallet client works with nothing else added. It is built from `NWC_URI`. Package discovery registers the service provider. If your app brings its own NWC client, bind `OpenReceive\Nwc\ReceiveNwcClient` in the container instead. Then run: ```sh php artisan openreceive:install php artisan migrate ``` `openreceive:install` writes three files: - `config/openreceive.php`: the settings. The host hook is a CLASS NAME, not a closure. `php artisan config:cache` serializes this file, and a closure anywhere in it makes the cache fail. - `app/OpenReceive/Host.php`: the three hooks (`authorize`, `amountFor`, `onPaid`), with the two generated placeholders wired in and the fulfillment note as comments. - `database/migrations/*_create_openreceive_tables.php`: one migration for both engine tables (`openreceive_payments` and `openreceive_meta`). Its DDL comes from the engine's `PaymentsSchema::statements()` for your connection's driver: PostgreSQL, MySQL/MariaDB or SQLite. `php artisan migrate` runs it like any of your own migrations. There is no second runner. → [OpenReceive\Storage](https://openreceive.org/guides/api-reference.md#openreceivestorage) There is no Eloquent model for the engine's tables, and you do not write one. 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. #### Fulfill exactly once Within OpenReceive's own settlement paths, `onPaid` runs at most once per reference. A second payment to a second invoice is recorded with `status_reason = "duplicate_settlement"` and never fulfills 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 `onPaid` must be idempotent. The generated `Host.php` explains this and shows the guarded transition: ```php public function onPaid(PaymentSettlement $settlement): void { $claimed = Order::where('id', $settlement->reference) ->where('state', 'awaiting_payment') ->update(['state' => 'paid', 'paid_at' => Carbon::createFromTimestampUTC($settlement->paidAt)]); if ($claimed === 0) { return; // someone else already fulfilled it } // The 'paid' state IS the flag. Ship the goods and send the mail from a job // that drains it after commit, or from afterPaid() below — never from here. } ``` Delivery is at-least-once. `onPaid` runs inside the settlement transaction. If it throws, the transaction rolls back and the next pass retries. So keep `onPaid` to database writes on the order. An email or webhook sent from here would survive the rollback and go out again. The `'paid'` transition above is the flag. Drain it after commit in one of two ways: - Let your own job drain it. - Implement `OpenReceive\Hosts\AfterPaid`. Its `afterPaid(PaymentSettlement $settlement)` runs after COMMIT, best-effort, for the same first settled attempt. Put `FulfillOrder::dispatch(…)` or an event there. Do not open a `DB::transaction()` of your own inside `onPaid`. The engine already holds the transaction on this connection, and PDO refuses a nested `BEGIN`. **A query-builder `update()` fires no model events.** 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 observer, no `saved` event and no `Model::updated` listener runs. That is fine for a job that drains the flag. It does not work for a model that owns the transition through events. If yours does, take a row lock for the duration instead: ```php public function onPaid(PaymentSettlement $settlement): void { $order = Order::lockForUpdate()->find($settlement->reference); // SELECT … FOR UPDATE if ($order === null || $order->state !== 'awaiting_payment') { return; } $order->update(['state' => 'paid', 'paid_at' => Carbon::createFromTimestampUTC($settlement->paidAt)]); // events fire } ``` **Unlocking a download works the same way.** If the payer bought a file, do not unlock it in the browser. Gate the download route on the paid order row, and serve the file only if that row exists: `Order::where('id', $id)->where('user_id', $request->user()->id)->where('state', 'paid')->firstOrFail()`, or a 404 otherwise. The `'paid'` written above is the unlock. The client never decides that an order was fulfilled. It re-reads the row. Buy a Button's `ShopController::download` does this in twenty lines. Both shapes are idempotent and correct. They differ only in whether your model layer runs: - The query-builder `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. 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/laravel`) 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 Laravel loads `.env` itself, and `config/openreceive.php` reads the values through `env()`: ```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)). Under `php artisan config:cache`, Laravel never reads `.env` at runtime. The values are captured when you cache, as with every other Laravel secret. So re-run `config:cache` after changing one. The engine redacts connection strings in every log line. `php artisan openreceive:doctor` prints each variable only as set or unset. → [Environment variables](https://openreceive.org/guides/environment-variables.md). ### Configure the host hooks `app/OpenReceive/Host.php` 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 `onPaid` 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. ```php action — "checkout.prepare", "checkout.create", "payment.check", // "swap.quote", "swap.create", "swap.read" or "swap.refund" // $context->request — the Illuminate\Http\Request: read the session, the // authenticated user, cookies or headers, as in a controller // $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 string (≤200 chars); payment_hash is null 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. public function authorize(AuthorizeContext $context): bool { $order = Order::find($context->reference()); return $order !== null && $order->user_id === $context->request->user()?->id; } // The price for a reference — here, your order id — from your own data; null // 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. public function amountFor(string $reference): ?array { $order = Order::find($reference); return $order === null ? null : [ 'currency' => 'USD', 'value' => $order->total, // a decimal string column 'description' => $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 // Eloquent on the default connection, because the engine holds the // transaction on that connection's PDO — the query joins it. public function onPaid(PaymentSettlement $settlement): void { Order::where('id', $settlement->reference) ->where('state', 'awaiting_payment') ->update(['state' => 'paid', 'paid_at' => Carbon::createFromTimestampUTC($settlement->paidAt)]); } } ``` `config/openreceive.php` names that class (`'host' => App\OpenReceive\Host::class`). The provider resolves it from the container, so it may take constructor dependencies. `onPaid` runs inside the settlement transaction, only for the first settled attempt for a reference. → [OpenReceive\Host](https://openreceive.org/guides/api-reference.md#openreceivehost) · [the authorize context](https://openreceive.org/guides/api-reference.md#the-authorize-context-php) The routes mount under `config('openreceive.route_prefix')` (`openreceive`), with the middleware in `config('openreceive.middleware')` (`['web']`). The `web` group is how the engine picks up your application's session and CSRF protection. Laravel's `VerifyCsrfToken` reads `X-CSRF-TOKEN`. The checkout client sends it automatically from ``, so keep that tag in the layout that renders the checkout. The `web` group also brings every middleware it carries. A global `auth` redirect on the `web` group would send the engine's JSON routes to a login page too. Keep such guards on your own route groups, not on `web` itself. The generated `Host.php` ships two placeholders. Replace both, not just `onPaid`: - `use LoggingOnPaid;` 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 the engine warns every time your application boots. - `use AllowAllAuthorize;` allows everything. It treats possession of the reference as authorization, which is safe only while references are unguessable. The engine warns at boot until you replace it with your own ownership check (as above). The amount always comes from your own order record. Payer-supplied amounts are rejected. The engine's `PaymentRepository` interface remains the escape hatch for apps with custom storage. It is not part of the quickstart. For public web shops, turn on the per-IP invoice cap with `'rate_limiting' => true`. Leave it off (the default) when many payers share one IP. The client IP is `$request->ip()`, so behind a proxy Laravel's `TrustProxies` decides who the payer is. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md) In production, the engine builds the wallet client when your app boots. It also runs the receive-only preflight right away: it reaches the wallet and checks that the code cannot spend. A missing `NWC_URI`, a dead relay, or a spend-capable wallet then stops the deploy. Otherwise those problems would show up as 500 errors for customers on the first checkout. Outside production (tests, consoles), the engine builds the client lazily, on first use, so no live wallet is needed. PHP builds the whole engine again on every request. Under PHP-FPM or Apache, that same preflight would then run per request. To avoid that, the package caches the wallet's info event in your default cache store for `config('openreceive.wallet_info_cache_seconds')` (600). A checkout request then costs one relay round trip, not two. ### 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 low specificity, so your own styles can override checkout styles. Scoping does not prevent that. The engine serves JSON checkout routes only. Your view does the rendering. Any OpenReceive frontend package works against the `/openreceive` mount. The smallest is the custom element. Its default `prefix` is already `/openreceive`. The package ships a self-contained `styles.css`, scoped to what OpenReceive renders. Laravel ships Vite, so the package installs like any other frontend dependency: ```sh npm install @openreceive/elements ``` ```js // resources/js/app.js — in the entry @vite() already loads import { defineElements } from "@openreceive/elements"; import "@openreceive/elements/styles.css"; // Registers the tag with the browser. Without this, // the tag in the Blade below is unknown markup and renders as nothing; with // it, the element wakes up wherever the tag appears. Call once per page — // order relative to the markup does not matter. defineElements(); ``` ```blade {{-- resources/views/orders/pay.blade.php --}} ``` The element creates the checkout for `reference`, then renders and polls itself. React, Vue, Svelte, and Angular apps use the matching wrapper package instead, with the same props and 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)). 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. **No npm in this project?** Every GitHub release attaches `standalone-checkout-.tar.gz`. It holds one self-registering ESM file, its stylesheet and a `MANIFEST.json` of hashes. Unpack it into `public/openreceive/`, and the same element needs just two tags: ```blade ``` `MANIFEST.json` carries the version and a SHA-256 per file. Keep the tarball version in step with the Composer package. ### 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 php artisan openreceive:notifications ``` The worker listens for the wallet's NWC-02 `payment_received` notifications. The same process also runs a periodic reconcile pass. Run one per deployment, not one per web instance. Two more commands help: - `php artisan openreceive:reconcile` runs one pass, if you want to drive it yourself. - `php artisan openreceive:doctor` reports every credential as set or unset, the host and its placeholders, the route mount, and the wallet preflight. ### Swap secrets The package 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 the `openreceive.swap_providers` container binding. Bind a list of your own adapters to replace the auto-built set, or `[]` to disable swaps. One `openreceive_payments` row holds at most one provider order, in its server-only `swap_data`. The engine never returns `swap_data` from its routes or writes it to a log. Do not select it into your own API, serialize it, or log it. 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`.