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

OpenReceive agent directions (Paymenter)

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

Install and configure the OpenReceive payment gateway in the Paymenter billing panel you are working in. Preserve its theme, clients, products, invoices and prices. The extension is one folder that bundles the PHP engine and the checkout’s script: do not install Composer or npm packages into Paymenter, and do not clone the OpenReceive repository.

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 clients pay with USDT, USDC, ETH or SOL instead; the provider converts the payment to BTC over Lightning in the merchant’s connected wallet. Available assets and networks depend on the provider.

Run every php artisan command below in Paymenter’s directory, as the web server’s user, never as root: a root run can leave Paymenter’s log file owned by root, and then every page fails. With Paymenter’s official Docker image, that is docker compose exec -T -u nginx paymenter php artisan … (-T passes stdin through; use the Paymenter service’s own name). On a server, it is sudo -u www-data php artisan … with the site’s own user.

Step 0 — ask for the two codes, one question at a time

Before anything else, check one thing: whether OpenReceive is already installed (php artisan openreceive:doctor). If the command exists, it prints NWC_URI: set or unset (likewise LSC_URI_PRIMARY), never the values. A code that is already set is not asked for again; if both are set, skip to Step 3.

Otherwise your next action is a question to the user. Do not download the extension, edit Docker files or search anywhere else before asking it. Do not read Paymenter’s .env, deploy config, container environments or other projects looking for a code: a new install has neither code yet.

The user never runs a command and never edits a file. They paste each code into this chat; you store it. That is the supported path: do not ask them to run the save command themselves, and do not tell them to revoke or replace a code because it was pasted here. Ask one question per message.

  1. First message — the NWC code, and nothing else.

    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.

  2. When they paste it. If it does not start with nostr+walletconnect://, ask them to copy the receive-only code again. Otherwise do not repeat it: reply only that you have it, then ask the next question. You store it in Step 2.

  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: do not skip it, and do not ask yes or no first. Otherwise ask whether clients 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. Swaps are now on, so keep the route back (the swap non-negotiable below).

Do not report setup as complete until the NWC code is saved, and the LSC code is saved or the user said “Bitcoin only”. Never invent a placeholder code.

Step 1 — install the extension

The extension is the ZIP attached to this GitHub release. It holds one OpenReceive folder, which goes into Paymenter’s extensions/Gateways/ directory. Never install the GitHub source-code ZIP or a ZIP from an older release. With Paymenter’s official Docker image, download and unpack it inside the container, as the web user:

docker compose exec -T -u nginx paymenter sh -c 'cd /app/extensions/Gateways && curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.28/openreceive-paymenter-0.4.28.zip && unzip -q openreceive-paymenter-0.4.28.zip && rm openreceive-paymenter-0.4.28.zip'
docker compose exec -T -u nginx paymenter php artisan app:extension:install gateway OpenReceive

On a server, unpack it into <paymenter>/extensions/Gateways/ the same way, make the folder the web user’s, and run the same app:extension:install. That command creates the extension’s two tables in Paymenter’s database and its gateway, “Bitcoin Lightning”. Checkout offers it once a wallet code is saved.

The extension needs Paymenter 1.5 or later on 64-bit PHP 8.3+ with GMP and sodium. The official image has all of them. If doctor reports a missing PHP extension on a server, say which one and stop: installing PHP extensions on the user’s server is theirs to decide.

Step 2 — store the codes

Store each code yourself, one per command, and never as a shell argument:

  1. Write the code with your file-editing tool, not a shell command (no echo, printf or heredoc), to a new file outside the Paymenter directory, such as /tmp/openreceive-code.
  2. Run php artisan openreceive:configure --nwc-uri=- < /tmp/openreceive-code. In Docker: docker compose exec -T -u nginx paymenter php artisan openreceive:configure --nwc-uri=- < /tmp/openreceive-code. For the LSC code, use --lsc-uri-primary=-.
  3. Delete the file (rm /tmp/openreceive-code), whether the command passed or not.

The command asks the wallet first and saves the code, encrypted with Paymenter’s APP_KEY, only when the wallet answers as receive-only; a failure saves nothing. If it reports spend methods such as pay_invoice, ask the user for a receive-only code again. Saving the swap code renames the gateway to “Bitcoin & stablecoins”. Never write a code into Paymenter’s settings table, .env or any file in the Paymenter directory yourself.

Then run php artisan openreceive:doctor. It names any failed check and exits nonzero; fix it before going on.

Step 3 — mint a test invoice, then stop

Create a small unpaid test invoice, billed to the first admin account without Paymenter’s new-invoice email, and mint its Lightning invoice:

php artisan openreceive:test-invoice --new

To use an invoice that already exists, pass its id instead of --new. test-invoice goes through the same route as the invoice’s payment dialog. It prints the amount in sats, the BOLT11 invoice, the invoice page and the methods the dialog offers, each swap asset marked available or followed by the reason it is not. That reason is the answer; report it. “Below the provider minimum” or “above the provider maximum” is about this invoice’s amount, not a fault. Only when the reason says the provider is unreachable does doctor’s “Swap provider” line have more detail. test-invoice and doctor are the whole check.

Give the user the invoice page; its Pay button opens the checkout on this same invoice. Tell them the test invoice is theirs to cancel.

You cannot pay the invoice: the code is receive-only. Do not pay, settle or mark the invoice 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 from the invoice page with their own wallet; afterwards the invoice reads paid.

Setup ends here. Once doctor is clean and the user has the link, your last message starts “Setup is finished” and has at most six short lines: the invoice page, the methods the checkout offers (Bitcoin, plus USDT, USDC, ETH and SOL when the swap code is saved), and one line of what to look at. Do not list each coin’s availability, mention a minimum, or say a coin will not work: a provider minimum depends on the invoice total, and real invoices will differ. Do not list what you changed or what doctor checked. Send nothing after it. Do not add containers, services, workers or cron jobs: Paymenter’s own cron job runs the extension’s every-minute pass. If doctor says Paymenter’s scheduler has never run, say so in one line of that message.

Non-negotiables

Further reading

The quickstart, in full

Inlined verbatim so this file needs no network access. Steps 0–3 above are the setup and this is their reference: where the two differ, the steps win, and its admin-area screens are only for a Paymenter with no shell. The page it comes from is https://openreceive.org/guides/quickstart-paymenter.

Paymenter quickstart

Paymenter is an open-source billing panel for hosting companies. The OpenReceive extension adds a payment method to it: the client pays an invoice with Bitcoin over Lightning, straight into your own wallet, from Paymenter’s own payment dialog. With a swap provider, the same dialog also takes USDT, USDC, SOL and ETH, which the provider converts to BTC over Lightning into the same wallet.

Paymenter keeps owning clients, invoices, prices and services. The extension keeps its payment attempts in two tables of Paymenter’s own database. When a payment settles, it records the payment on the invoice with Paymenter’s own payment call, so the invoice turns paid and Paymenter activates or renews the service as it does for any other gateway.

Requirements: Paymenter 1.5 or later, on 64-bit PHP 8.3 or later with GMP and sodium, and MySQL or MariaDB. Paymenter’s official Docker image has all of them. Paymenter’s cron job must run, as Paymenter’s own install guide sets up.

Install the extension

Each GitHub release attaches the extension as a ZIP that holds one OpenReceive folder. It belongs in Paymenter’s extensions/Gateways/ directory, next to Stripe and PayPal:

cd /var/www/paymenter
curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.28/openreceive-paymenter-0.4.28.zip
unzip -q openreceive-paymenter-0.4.28.zip -d extensions/Gateways
rm openreceive-paymenter-0.4.28.zip
chown -R www-data:www-data extensions/Gateways/OpenReceive
sudo -u www-data php artisan app:extension:install gateway OpenReceive

Use your own Paymenter directory and web server user. The last command creates the extension’s two tables and its gateway, named “Bitcoin Lightning”. Until a wallet code is saved, checkout does not offer it.

The ZIP already bundles the extension’s dependencies and the checkout’s script, under their own prefixed names, so Composer never runs and nothing in Paymenter’s own vendor/ changes. Paymenter updates leave the folder alone. The GitHub source-code ZIP is not an installable extension.

Paymenter in Docker

The official Compose file mounts ./extensions into the container, so unzip into the extensions/Gateways folder next to compose.yml. Run the artisan commands inside the container as its web user, nginx:

docker compose exec -u nginx paymenter php artisan app:extension:install gateway OpenReceive

Always pass -u nginx. A command that runs as root can create Paymenter’s daily log file as root, and every web request then fails with a 500 until you fix the ownership with chown -R nginx:nginx /app/storage.

Configure the wallet

You need a receive-only NWC code: a Nostr Wallet Connect code that can create invoices and read payments but cannot spend. The extension refuses a code that can spend.

In the admin area, open Gateways, edit Bitcoin Lightning, paste the code into Receive-only NWC code and save. To accept stablecoins too, paste a swap provider code into Swap provider code. Paymenter stores both encrypted with its APP_KEY.

From a terminal, pipe each code into openreceive:configure from your secret manager or a protected file. Never type a code as a command argument:

sudo -u www-data php artisan openreceive:configure --nwc-uri=- < /secure/path/wallet-code
sudo -u www-data php artisan openreceive:configure --lsc-uri-primary=- < /secure/path/swap-code
sudo -u www-data php artisan openreceive:doctor

configure asks the wallet first and saves the code only when it answers as a receive-only wallet. Saving a swap code renames the default “Bitcoin Lightning” to “Bitcoin & stablecoins”; --name="…" sets your own. Omit the swap command for Bitcoin-only checkout.

doctor checks the gateway, GMP and sodium, each code as set or unset (never its value), the tables, the routes, the wallet, the price feed for every Paymenter currency, each swap provider and the scheduled pass. It exits nonzero when a check fails.

Check it

Make a Lightning invoice through the same route the payment dialog uses, for a new $5 test invoice billed to the first admin account, or for any unpaid invoice by its id:

sudo -u www-data php artisan openreceive:test-invoice --new
sudo -u www-data php artisan openreceive:test-invoice <invoice id>

--new sends no new-invoice email; --amount= and --user=<email> change what it bills and to whom. Cancel the test invoice in the admin area when you are done.

It prints the amount in sats, the Lightning invoice and the invoice page, then each method the dialog offers: Bitcoin Lightning, and each swap asset with its network and whether it is available for this amount. A small invoice is often below a swap provider’s minimum; that is the amount, not a fault.

How a payment works

  1. The client opens the invoice, presses Pay and picks the OpenReceive method. The checkout opens inside Paymenter’s payment dialog.
  2. The extension charges what is still due on the invoice, in the invoice’s currency, converted to sats at the current BTC price. Only the client the invoice belongs to, signed in, can make or follow its payment.
  3. Once the wallet reports the payment, the extension records it on the invoice in the same database transaction that settles it. The payment hash is the transaction id. Paymenter then marks the invoice paid and runs its usual work, such as activating the service and sending the receipt.
  4. The dialog returns the client to the invoice, now paid.

The checkout asks the wallet while the dialog is open. If the client closes it before the payment settles, the extension’s pass on Paymenter’s scheduler finds the payment within a minute or so. php artisan openreceive:reconcile runs one pass by hand.

A client who closes the dialog and comes back to the invoice gets the same Lightning invoice again while it is still valid.

Refunds and removal

The receive-only wallet cannot send refunds. Send a refund from your own wallet, then record it in Paymenter. A client whose swap deposit never converted reclaims it from the same invoice’s payment dialog, while the invoice is still unpaid. If you turn on swaps, you commit to keeping that path available. See swap refunds.

Deleting the gateway keeps the two tables: they are a record of payments received.

Tested, and not tested

Tested on 2026-10-16 with Paymenter 1.5.9’s official Docker image and MariaDB 11.8, a test wallet and a test swap provider: install from the built ZIP, configure from stdin, the doctor, and a client paying an invoice by Lightning in Chromium, after which the invoice reads paid with the payment hash as its transaction.

Not tested: PostgreSQL or SQLite, Paymenter in a subdirectory of a domain, and Paymenter’s automatic charges of saved payment methods. Lightning cannot pull a payment, so OpenReceive offers no saved payment method: the client pays each renewal invoice.