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

OpenReceive agent directions (PHP)

# READ THIS FIRST: this file is 38 KB and a summary drops required steps. Download it whole:
curl -fsSL https://openreceive.org/agent-directions/php/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 PHP application — the app you are already working in. You do not need a copy of the OpenReceive source: the engine is on Packagist (openreceive/openreceive), the checkout UI is a tarball on every GitHub release, 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 PSR-15 handler it ships — 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 (shop_orders, a signed-cookie visitor, a SQLite catalog) 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 router, its session/authentication and its database. The engine is framework-free: it wants a PDO handle, one object with three methods, and a place in your front controller (or middleware stack) to dispatch /openreceive/* to its PSR-15 handler. If this app runs Laravel, use the openreceive/laravel adapter and its own directions instead of this page. Reuse the app’s existing session or cookie in authorize and the PDO it already opens in PdoConnection.

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 OpenReceive\Host; 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 run composer require, edit the app, write .env.example, or search anywhere else before asking it. Do not read deploy config (compose files, SetEnv/fastcgi_param blocks, platform 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:

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. Nothing in PHP reads .env on its own. Add vlucas/phpdotenv and load the file in the front controller before Service::fromEnvironment(). When the app is started with Docker Compose, give the service env_file: .env. Restart PHP-FPM or 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.

Then check the PHP runtime: php -m must list gmp, sodium, mbstring, json, pdo and one PDO driver. ext-gmp is REQUIRED — the NWC transport signs every request with it — and php:*-cli/-fpm images do not ship it (docker-php-ext-install gmp). PHP must be ≥ 8.2 and 64-bit.

Upgrading an existing install

This is not the opening move of a new integration. When OpenReceive is ALREADY installed here, OpenReceive\Server\Doctor::report() (a plain host runs it from the quickstart’s bin/doctor script) reports every credential as set/unset (never the value), the host class and any placeholder hooks, the mount, and the wallet preflight. Check the installed openreceive/openreceive (composer show openreceive/openreceive) and the unpacked checkout’s MANIFEST.json against the release named at the top of this file. The two must match: the browser build and the engine are one release. 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 the quickstart’s bin/doctor script 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 step 6 (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

PaymentsSchema::statements($dialect) renders openreceive_payments and openreceive_meta for THIS application’s database; run it through the app’s own migration tool. 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 drop-in (<openreceive-checkout>, from the release’s standalone tarball or @openreceive/elements) already obeys 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-php.

PHP quickstart (plain PHP)

This page is for plain PHP, with no framework: a front controller, a PDO handle and three methods. Laravel has its own quickstart (openreceive/laravel, the thin adapter over this engine).

Requires PHP ≥ 8.2 (64-bit) with ext-gmp, ext-sodium, ext-mbstring, ext-json, ext-pdo and one PDO driver (pdo_pgsql, pdo_sqlite or pdo_mysql). ext-gmp is required, not optional. The NWC transport signs every wallet request with it.

1. Install

composer require openreceive/openreceive nyholm/psr7 nyholm/psr7-server

openreceive/openreceive is the whole engine. It includes the receive-only wallet client, exact money, settlement, the openreceive_payments repository over PDO, swaps, rates and a PSR-15 handler. It depends only on the PSR interfaces, so bring the PSR-7/PSR-17 implementation your app already has. nyholm/psr7 + nyholm/psr7-server is the smallest pair, and this page uses it.

The checkout UI is not in the Composer package. Packagist installs from git and cannot run a JS build. So the browser side ships separately, as standalone-checkout-<version>.tar.gz on every GitHub release. It holds one self-contained ES module, its stylesheet, a source map and a MANIFEST.json. Unpack it somewhere your web server serves static files (step 5). If your app has a JS bundler, you can npm install @openreceive/elements instead. The tarball is the same build.

2. Migrate the payment tables

The engine owns two tables in your database and renders their DDL for each SQL dialect. Run that DDL through whatever your app uses for schema changes: Phinx, Doctrine Migrations, a plain SQL file, or a bin/migrate script.

use OpenReceive\Storage\PaymentsSchema;

// $dialect is 'pgsql', 'mysql' or 'sqlite' (PDO::ATTR_DRIVER_NAME gives it to you).
foreach (PaymentsSchema::statements($dialect) as $sql) {
    $pdo->exec($sql);
}
// down(): PaymentsSchema::dropStatements()

If your script has no migration tool, PaymentsSchema::migrate(new PdoConnection($pdo)) does the same in one call. It creates two tables. Leave both to the library:

Details: Payment storage.

3. Add wallet credentials

Create a server-only .env, or export the variables from your process manager. The engine reads getenv() and $_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).

Nothing in PHP loads a .env file on its own. Something has to put the values in the process environment first: vlucas/phpdotenv, your web server’s SetEnv/fastcgi_param, or the container runtime (Environment variables).

4. Wire OpenReceive

Three methods on one object are the entire bridge between the engine and your data. The engine never sees an order, a user or a price except through them. Engine combines the wallet, the repository over your PDO, and that object into a PSR-15 handler. Your front controller sends requests under one path prefix to that handler:

<?php
// public/index.php — or wherever your front controller lives
declare(strict_types=1);

use Nyholm\Psr7\Factory\Psr17Factory;
use Nyholm\Psr7Server\ServerRequestCreator;
use OpenReceive\Host;
use OpenReceive\PaymentSettlement;
use OpenReceive\Server\AuthorizeContext;
use OpenReceive\Server\Engine;
use OpenReceive\Server\Service;
use OpenReceive\Storage\PdoConnection;
use OpenReceive\Storage\SqlPaymentRepository;

require __DIR__ . '/../vendor/autoload.php';

$pdo = new PDO(getenv('DATABASE_DSN'));        // the PDO your app already opens
$orders = new App\Orders($pdo);                // YOUR order model — any name works

$host = new class($orders) implements Host {
    public function __construct(private readonly App\Orders $orders) {}

    // Your own access check: may this caller do this action to this reference?
    // `$context->reference()` is your order id, sent back by the payer's
    // browser — a claim, not proof — already validated as a non-empty string.
    // `$context->request` is the PSR-7 ServerRequest: read your session or
    // cookie from it. `$context->action` names the route (checkout.create, …).
    public function authorize(AuthorizeContext $context): bool
    {
        $order = $this->orders->find($context->reference());
        return $order !== null && $order->userId === App\Session::userId($context->request);
    }

    // The price for a reference from YOUR data. `value` is a decimal STRING,
    // never a float and never a request parameter; `description` is what the
    // payer is buying, rendered above the amount. null = nothing to pay (404).
    public function amountFor(string $reference): ?array
    {
        $order = $this->orders->find($reference);
        return $order === null ? null : [
            'currency' => 'USD',
            'value' => $order->total,               // "12.00"
            'description' => "{$order->lineCount} items",
        ];
    }

    // INSIDE the settlement transaction, once per reference. Write through
    // `$settlement->connection` — that transaction — so your order flips in the
    // same commit as the payment record. The WHERE clause is the lock: a second
    // fulfillment path of yours updates zero rows. Database writes only here;
    // emails and webhooks go after commit (implement Hosts\AfterPaid for that).
    public function onPaid(PaymentSettlement $settlement): void
    {
        $settlement->connection->execute(
            "UPDATE orders SET state = 'paid', paid_at = ? WHERE id = ? AND state = 'awaiting_payment'",
            [$settlement->paidAt, $settlement->reference],
        );
    }
};

$engine = new Engine(
    $host,
    new SqlPaymentRepository(new PdoConnection($pdo)),
    Service::fromEnvironment(),                    // NWC_URI (+ LSC_URI_*) from the environment; preflight runs here
    prefix: '/openreceive',
);

$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
if (str_starts_with($path, '/openreceive')) {
    $factory = new Psr17Factory();
    $request = (new ServerRequestCreator($factory, $factory, $factory, $factory))->fromGlobals();
    $response = $engine->psr15Handler()->handle($request);
    http_response_code($response->getStatusCode());
    foreach ($response->getHeaders() as $name => $values) {
        foreach ($values as $value) header("{$name}: {$value}", false);
    }
    echo $response->getBody();
    return;
}
// … your own routes

Service::fromEnvironment() builds the wallet client from NWC_URI and runs the receive-only preflight. A missing, invalid or spend-capable code throws before any route is served. PHP starts every request from nothing, so that check runs on every request that reaches the engine.

The settlement gate the engine relies on lives in openreceive_meta, not in memory. That is why a fleet of PHP-FPM workers shares one wallet-scan budget, with no worker process of its own. Later OpenReceive requests also settle pending invoices, so a payer who closes the tab is still covered. authorize runs on every request. → Engine · Host · the authorize context

Cross-site requests. Plain PHP has no CSRF layer, just like Express, and the engine does not need one. Every mounted route refuses a request whose Sec-Fetch-Site header says cross-site. So a form or script on another origin cannot create invoices using a payer’s cookie. That makes <meta name="csrf-token"> optional. If you set it, the checkout sends the value back as X-CSRF-Token (or the header named by csrf-header) for your own layer to check.

The engine’s check does NOT cover two cases:

authorize is still the boundary that decides whether this caller may act on this order (Security).

For public web shops, turn on the per-IP invoice cap with rateLimiting: true on Engine. Leave it off (the default) when many payers share one IP. Behind a proxy, pass clientIp: fn ($request) => … so the cap counts the payer, not the proxy. → Rate limiting

Your app also needs an ordinary order-creation route. It validates the cart, prices with exact decimal math, and returns the order id. The page then passes that id as the reference. OpenReceive never prices from payer input.

The reference is a string you choose, and it is the fulfillment identity. Use your order id:

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.

Naming: PHP APIs use camelCase methods and snake_case array keys (amount_msats, payment_hash). The keys match the wire format. The mounted HTTP routes and the browser snapshots are snake_case throughout.

5. Render 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.

Unpack the release’s standalone-checkout-<version>.tar.gz into a directory your web server serves. This page uses public/openreceive/. Then add two tags and the element:

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

<openreceive-checkout
  reference="<?= htmlspecialchars($order->id) ?>"
  prefix="/openreceive"
></openreceive-checkout>

The module registers <openreceive-checkout> as it loads. The element creates the checkout for reference, then renders, polls and settles itself. The stylesheet is scoped to what OpenReceive renders. The checkout follows the payer’s theme. On a page that always uses one theme, lock it with theme="dark". React, Vue, Svelte, and Angular apps use the matching wrapper package instead, with the same attributes (Frontend checkout). A custom UI builds on @openreceive/browser/headless (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).

MANIFEST.json in the tarball carries the version and a SHA-256 per file. You can use it to check a copied tree against the release it came from. Keep the tarball version in step with the Composer package.

Buy a Button (examples/buttons/server/php-plain) 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.

6. Verify

foreach (\OpenReceive\Server\Doctor::report(
    \OpenReceive\Server\Service::processEnvironment(),
    $host,
    static fn () => \OpenReceive\Server\Service::fromEnvironment(),
    '/openreceive',
) as $line) echo $line, PHP_EOL;

Doctor::report() prints:

$engine->doctor() is the same report for an engine you already built. Put it behind a bin/doctor script. The demo’s is twelve lines. → Doctor

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.

Reconciliation

Settlement runs on the request path. Every payment route first runs one bounded reconcile pass through the durable openreceive_meta gate. The gate allows at most one real wallet scan every 3 seconds, shared by every PHP process. You do not need a cron job. Tune or disable it with Engine’s opportunisticReconcile (false, or ['min_interval_seconds' => …]).

Optionally, run one worker so settlement does not wait for the next page load:

$engine->notificationsWorker()->run();   // blocks: an NWC-02 listener plus a periodic pass

Run it as its own long-lived process (php bin/notifications). To run a pass yourself, use the one-shot $engine->reconcile(). → Engine notificationsWorker

Swap secrets

Setting LSC_URI_PRIMARY (and LSC_URI_BACKUP) auto-builds the matching swap providers. Nothing in your code changes. One openreceive_payments row holds at most one provider order, in its server-only swap_data. The repository never selects it into public arrays. Do not log it or return it from your own API.

Setting either connection string commits you to refunds. A deposit that arrives short or late is claimed on a second visit. That needs a per-order URL your app serves, and the attempt’s payment_hash kept. Swap refunds covers all of it. Read it before you set LSC_URI_PRIMARY.