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

OpenReceive agent directions (PrestaShop)

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

Install and configure the OpenReceive payment module in the PrestaShop store you are working in. Preserve its theme, customers, products, orders and prices. The module is a ZIP that bundles the PHP engine and the checkout’s script: do not install Composer or npm packages into PrestaShop, 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 customers 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 command below in PrestaShop’s folder (the one that holds bin/console), as the web server’s user, never as root: a root run can leave files in PrestaShop’s var/cache that the web server cannot write. With PrestaShop’s official Docker image, that is docker compose exec -T -u www-data prestashop php bin/console … (-T passes stdin through; use the PrestaShop service’s own name; the container starts in /var/www/html). On a server, it is sudo -u www-data php bin/console … 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 bin/console 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 module, edit Docker files or search anywhere else before asking it. Do not read PrestaShop’s app/config/parameters.php, 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 customers 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 module

The module needs PrestaShop 9 on 64-bit PHP 8.2+ with GMP and sodium. Check first: php -m must list both gmp and sodium. PrestaShop’s official Docker image has sodium but not GMP, so with it, build an image that adds GMP:

  1. Put a Dockerfile next to the Compose file, with the same tag as the PrestaShop service’s image: line:

    FROM prestashop/prestashop:<tag>
RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
 && docker-php-ext-install gmp && rm -rf /var/lib/apt/lists/*
  2. In the Compose file, replace that service’s image: line with build: . (the folder that holds the Dockerfile). Change nothing else in the file.
  3. Run docker compose up -d --build. PrestaShop’s files and configuration stay in the service’s volume; only PHP changes. Check php -m again.

On a server without GMP, say which PHP extension is missing and stop: installing PHP extensions on the user’s server is theirs to decide. On PrestaShop 8, whose PHP stops at 8.1, say the module needs PrestaShop 9 and stop.

The module is the ZIP attached to this GitHub release, one openreceive folder. Unzip it into PrestaShop’s modules folder; it changes no PrestaShop file. Never install the GitHub source-code ZIP or a ZIP from an older release. With the Docker image, download and unpack it inside the container, as the web user, then install the module with PrestaShop’s own console:

docker compose exec -T -u www-data prestashop sh -c 'curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.30/openreceive-prestashop-0.4.30.zip && unzip -oq openreceive-prestashop-0.4.30.zip -d modules && rm openreceive-prestashop-0.4.30.zip'
docker compose exec -T -u www-data prestashop php bin/console prestashop:module install openreceive

On a server, unpack it into modules the same way, make modules/openreceive the web user’s, and run the same prestashop:module install openreceive. Installing creates the module’s two tables in PrestaShop’s database and its order state, “Awaiting Bitcoin payment”, adds the payment option to checkout and makes the openreceive:* console commands appear. The option stays hidden until a wallet code is saved.

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 PrestaShop folder, such as /tmp/openreceive-code.
  2. Run php bin/console openreceive:configure --nwc-uri=- < /tmp/openreceive-code. In Docker: docker compose exec -T -u www-data prestashop php bin/console 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 the shop’s own 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 wallet code turns the payment option on; saving the swap code renames it to “Bitcoin & stablecoins”. Never write a code into PrestaShop’s database, app/config/parameters.php or any file in the PrestaShop folder yourself.

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

Step 3 — mint a test invoice, then stop

Place a small test order for a hidden test product, bought by a test customer the command creates once (openreceive-test@example.invalid, so no real customer sees it and no email reaches anyone), and mint its Lightning invoice:

php bin/console openreceive:test-invoice --new

To use an order that already awaits its OpenReceive payment, pass its id instead of --new. test-invoice goes through the same route as the order’s confirmation page. It prints the amount in sats, the BOLT11 invoice, the order’s confirmation page and the methods the checkout 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 order’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 order’s confirmation page, which opens the checkout on this same invoice in any browser. Tell them to cancel the test order under Orders when they are done: PrestaShop keeps every order.

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

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 order’s page, the methods the checkout offers (Bitcoin, plus USDT, USDC, ETH and SOL when the swap code is saved), the cron line below, 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 order total, and real orders will differ. Do not list what you changed or what doctor checked. Send nothing after it.

PrestaShop has no scheduler, so the module’s pass for customers who leave the page before their payment settles needs one cron line, every five minutes: php bin/console openreceive:reconcile as the web user. Give the user that line in your last message; do not add it yourself, and do not add containers, services or workers.

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 back-office screens are only for a PrestaShop with no shell. The page it comes from is https://openreceive.org/guides/quickstart-prestashop.

PrestaShop quickstart

PrestaShop is an open-source e-commerce platform. The OpenReceive module adds a payment option to it: the customer pays with Bitcoin over Lightning, straight into your own wallet, on PrestaShop’s own order confirmation page. With a swap provider, the same page also takes USDT, USDC, SOL and ETH, which the provider converts to BTC over Lightning into the same wallet.

PrestaShop keeps owning customers, orders, prices and carriers. The module keeps its payment attempts in two tables of PrestaShop’s own database. When a payment settles, it records it the way PrestaShop’s payment modules do: an order payment with the payment hash as its transaction id, in the same database transaction that settles the payment. The order then moves to PrestaShop’s “Payment accepted”, so PrestaShop makes the invoice, emails the customer and runs its other modules as it does for any other payment.

Requirements: PrestaShop 9, on 64-bit PHP 8.2 or later with GMP and sodium, and PrestaShop’s MySQL or MariaDB database. PrestaShop 8 runs on PHP 8.1 at most, below what the module needs. A cron job runs the module’s reconcile pass, as below.

Already run BTCPay Server? PrestaShop via BTCPay Server is the other way in: BTCPay’s own PrestaShop module, with OpenReceive inside BTCPay.

Install the module

Each GitHub release attaches the module as a ZIP with one folder, openreceive. In the back office, open Modules → Module Manager, click Upload a module and drop the ZIP in: PrestaShop unpacks it into modules/openreceive and installs it.

From a shell, unzip it into PrestaShop’s modules folder instead, and install it with PrestaShop’s own console, in the folder that holds bin/console:

cd /var/www/html
curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.30/openreceive-prestashop-0.4.30.zip
unzip -oq openreceive-prestashop-0.4.30.zip -d modules
rm openreceive-prestashop-0.4.30.zip
chown -R www-data:www-data modules/openreceive
sudo -u www-data php bin/console prestashop:module install openreceive

Use your own PrestaShop folder and web server user. Installing creates the module’s two tables and its order state, “Awaiting Bitcoin payment”, and adds the payment option to checkout. The option stays hidden until a wallet code is saved.

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

PrestaShop in Docker

PrestaShop’s official image has sodium but not GMP. Build your own image on top of it: put this Dockerfile next to your compose.yml, use the same tag as your image,

FROM prestashop/prestashop:9.2.0-apache
RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
 && docker-php-ext-install gmp && rm -rf /var/lib/apt/lists/*

and in compose.yml replace the PrestaShop service’s image: line with build: ., then run docker compose up -d --build. PrestaShop’s files, its configuration and the module stay in the named volume at /var/www/html; only PHP changes.

Run every command inside the container, in /var/www/html, as its web user www-data. Unpack the release there too:

docker compose exec -T -u www-data prestashop sh -c 'curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.30/openreceive-prestashop-0.4.30.zip && unzip -oq openreceive-prestashop-0.4.30.zip -d modules && rm openreceive-prestashop-0.4.30.zip'
docker compose exec -T -u www-data prestashop php bin/console prestashop:module install openreceive

Always pass -u www-data. A command that runs as root can leave files in PrestaShop’s var/cache that the web server cannot write.

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 module refuses a code that can spend.

In the back office, open Modules → Module Manager and click Configure on OpenReceive. Paste the code into Receive-only NWC code and save. To accept stablecoins too, paste a swap provider code into Swap provider code. PrestaShop stores both encrypted with the shop’s own key, and the page never shows them again; it says only whether each is set.

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 bin/console openreceive:configure --nwc-uri=- < /secure/path/wallet-code
sudo -u www-data php bin/console openreceive:configure --lsc-uri-primary=- < /secure/path/swap-code
sudo -u www-data php bin/console openreceive:doctor

The settings page and configure both ask the wallet first and save the code only when it answers as a receive-only wallet. Saving the wallet code turns the payment option on. Saving a swap code renames the default “Bitcoin Lightning” to “Bitcoin & stablecoins”; the settings page’s Payment option name, or --name="…", sets your own. Skip the swap code for Bitcoin-only checkout. Checkout offers the option in the currencies ticked for OpenReceive under Payment → Preferences; installing ticks them all.

doctor checks the module, PHP and its GMP and sodium, each code as set or unset (never its value), the order state, the payment option and its currencies, the tables, the checkout’s files, the wallet, the price feed for every currency the shop sells in, each swap provider, and when the wallet was last scanned. It exits nonzero when a check fails.

The cron job

PrestaShop has no scheduler of its own. While a customer has an order’s page open, its checkout records the payment the moment it settles. For a customer who closes the page first, run the module’s reconcile pass every five minutes from cron, as the web server’s user:

*/5 * * * * www-data php /var/www/html/bin/console openreceive:reconcile

That line goes in /etc/cron.d/; in the web user’s own crontab, leave out www-data. On hosting with a control panel, add a cron job with the same php …/bin/console openreceive:reconcile command. With Docker, the host’s cron runs docker compose exec -T -u www-data prestashop php bin/console openreceive:reconcile from the Compose project’s folder.

Each pass also finishes any order whose payment settled but which did not move to “Payment accepted”, and every checkout request runs one pass too.

Check it

Make a Lightning invoice through the same route the order page uses, for a new $5 test order, or for any order awaiting its OpenReceive payment by its id:

sudo -u www-data php bin/console openreceive:test-invoice --new
sudo -u www-data php bin/console openreceive:test-invoice <order id>

--new places an order for a hidden, downloadable test product, bought by a test customer it creates once, openreceive-test@example.invalid, so no real customer sees the order and its email reaches no one. --amount= changes what it costs. PrestaShop keeps every order: cancel the test order under Orders when you are done. Like any new order, it may reach the back office’s notifications.

It prints the amount in sats, the Lightning invoice and the order’s confirmation page, then each method the checkout offers: Bitcoin Lightning, and each swap asset with its network and whether it is available for this amount. A small order is often below a swap provider’s minimum; that is the amount, not a fault. The order’s confirmation page carries the order’s secret key, so it opens the checkout in any browser.

How a payment works

  1. The customer picks the OpenReceive option at checkout and places the order. PrestaShop creates the order in “Awaiting Bitcoin payment” and opens its order confirmation page with the checkout on it.
  2. The module charges the order’s total with tax and shipping, in the order’s currency, converted to sats at the current BTC price. Only the customer the order belongs to, signed in, or a browser PrestaShop already showed the order to (its confirmation page, which needs the order’s secret key, or guest order tracking) may make or follow its payment, and only from a page with the order’s checkout, whose token comes back with each request.
  3. Once the wallet reports the payment, the module records an order payment for it, with the payment hash as its transaction id, in the same database transaction that settles it. Right after, the order moves to “Payment accepted”: PrestaShop makes the invoice, emails the customer and runs its other modules’ hooks. Should that step fail, the next pass finishes it.
  4. The page loads again and says the payment was received.

A customer who leaves can come back from Order history in their account, or a guest from Guest order tracking: the order’s page shows the checkout again while the order awaits its payment, with the same Lightning invoice while it is still valid.

An unpaid order stays in “Awaiting Bitcoin payment” until you cancel it, as with any other payment that never came. If you cancel an order and its payment arrives afterwards, the module records the payment on the order, leaves the order cancelled, and logs a warning.

Every line the module logs goes to PrestaShop’s var/logs/openreceive.log. Warnings and errors also appear under Advanced Parameters → Logs in the back office.

Refunds and removal

The receive-only wallet cannot send refunds. Send a refund from your own wallet, then record it in PrestaShop. A customer whose swap deposit never converted reclaims it from the same order’s page, while the order still awaits its payment. If you turn on swaps, you commit to keeping that path available. See swap refunds.

Disabling the module hides the payment option and its checkout. Uninstalling it also forgets both codes. It keeps the two tables, which are a record of payments received, and the “Awaiting Bitcoin payment” order state, which orders refer to.

Tested, and not tested

Tested on 2026-10-19 with PrestaShop 9.2.0’s official Docker image with GMP added (PHP 8.5), its Hummingbird theme, MariaDB 11.8, a test wallet and a test swap provider: the module uploaded through Upload a module in the back office, and installed from the unzipped ZIP with bin/console prestashop:module install; the swap code saved on the Configure page and both codes from stdin; the doctor; test-invoice --new; and in Chromium, a signed-in customer checking out with OpenReceive and paying on the order confirmation page by Lightning and by USDT on Solana, after which each order reads “Payment accepted” with its invoice. Coming back to the order through Order history resumed the same Lightning invoice. Another customer, with an order of their own, and a visitor were refused. A payment that settled with no page open was recorded by openreceive:reconcile. Uninstalling kept the payment records and the order state and forgot the codes.

Not tested: PrestaShop 9.0 and 9.1, the Classic theme, nginx with PHP-FPM, shared hosting, multistore, friendly URLs turned off, guest checkout and guest order tracking, carts PrestaShop splits into several orders, and updating from an older release of the module.