This is the full file; follow it from Step 0.

OpenReceive agent directions (Laravel)

# READ THIS FIRST: this file is 42 KB and a summary drops required steps. Download it whole:
curl -fsSL https://openreceive.org/agent-directions/laravel/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):

These directions describe OpenReceive 0.4.19.

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, 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, 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:

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=<paste> 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=<paste> 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. 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. 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: 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 onPaid 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.

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.

If you build your own checkout UI

The engine serves JSON only, so the view is yours — but the drop-ins (<openreceive-checkout>, React’s <Checkout>) 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.

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.

Questions, or a problem with the library itself: https://openreceive.org/contact

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:

php -m lists what your build has. To add gmp on Debian/Ubuntu, run apt-get install php8.2-gmp. In the official Docker image, run docker-php-ext-install gmp.

Add the Laravel package:

composer require openreceive/laravel

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:

php artisan openreceive:install
php artisan migrate

openreceive:install writes three files:

→ OpenReceive\Storage

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:

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:

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:

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 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():

NWC_URI=
LSC_URI_PRIMARY=
LSC_URI_BACKUP=
  1. Get a receive-only NWC code from a compatible wallet (get one here). Put it in NWC_URI.
  2. Optional: set up a 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).

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.

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:

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

namespace App\OpenReceive;

use App\Models\Order;                      // YOUR model — it could be named anything.
use Carbon\Carbon;
use OpenReceive\Host as OpenReceiveHost;
use OpenReceive\PaymentSettlement;
use OpenReceive\Server\AuthorizeContext;

final class Host implements OpenReceiveHost
{
    // Your policy, called before every checkout/payment/swap request.
    //   $context->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 · the authorize context

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 <meta name="csrf-token" content="{{ csrf_token() }}">, 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:

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

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 <link rel="stylesheet">. 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 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:

npm install @openreceive/elements

// resources/js/app.js — in the entry @vite() already loads
import { defineElements } from "@openreceive/elements";
import "@openreceive/elements/styles.css";

// Registers the <openreceive-checkout> 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();

{{-- resources/views/orders/pay.blade.php --}}
<openreceive-checkout reference="{{ $order->id }}"></openreceive-checkout>

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). Build a custom checkout only if this app cannot use a drop-in. In that case @openreceive/browser/headless is the API (Headless checkout).

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).

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-<version>.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:

<link rel="stylesheet" href="/openreceive/openreceive-checkout.css" />
<script type="module" src="/openreceive/openreceive-checkout.js"></script>

<openreceive-checkout reference="{{ $order->id }}"></openreceive-checkout>

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:

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:

Swap secrets

The package recognizes LSC_URI_PRIMARY and LSC_URI_BACKUP, using the shared Lightning Swap Connect vectors. Setting either one auto-builds the matching provider. So an app that wants swaps only supplies the connection strings (Environment variables). 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:

Swap refunds covers all of it. Read it before you set LSC_URI_PRIMARY.