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

OpenReceive agent directions (Rails)

# READ THIS FIRST: this file is 40 KB and a summary drops required steps. Download it whole:
curl -fsSL https://openreceive.org/agent-directions/rails/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 Rails application — the app you are already working in. You do not need a copy of the OpenReceive source: the gem is on RubyGems, 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 gem and the mounted engine routes — 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, a signed-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 Devise/session authentication and its database. Pick the frontend package that matches what already renders here (@openreceive/elements for ERB/Hotwire; /react, /vue, /svelte or /angular for an existing SPA) — do not add React to a Hotwire app. Reuse the app’s existing session or current_user in config.authorize; the engine’s migration adds only its own two tables to the app’s database.

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 — config.authorize, config.amount_for, config.on_paid; 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 gem, edit the app, write .env.example, or search anywhere else before asking it. Do not read Rails credentials, deploy config (config/deploy.yml, .kamal/secrets, compose files), 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. Rails does not read .env on its own. When the app is started with bin/rails or bin/dev, add dotenv-rails to the Gemfile. When it is started with Docker Compose, give the service env_file: .env. Restart the server after writing the file; the values are read at boot.

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, bin/rails openreceive:doctor reports every credential as set/unset (never the value), the engine mount, the three hooks, and the wallet preflight. Check the installed openreceive-rails 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: the gems are baked into the image, so an in-place bundle 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 bin/rails 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 on_paid 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-rails.

Rails quickstart

Requires Ruby ≥ 3.2 and Rails ≥ 8.0.

Add the Rails engine gem to your Gemfile:

gem "openreceive-rails"

That is the whole install. openreceive-rails depends on openreceive, openreceive-server and nwc-ruby, so the default wallet client works with nothing else added. It is built from NWC_URI. If your app brings its own NWC client, set config.nwc_client instead.

There is one native prerequisite. nwc-ruby uses rbsecp256k1, which builds libsecp256k1 from source. Minimal images (ruby:3.3-slim, fresh Docker builds) need the autotools for that, or bundle install fails with autoreconf: not found. Install them before bundling:

apt-get install -y autoconf automake libtool build-essential pkg-config

Full Ruby images and typical developer machines already have these.

Then run:

bin/rails generate openreceive:install
bin/rails db:migrate

The migration adapts to your app’s database adapter. PostgreSQL, SQLite, and MySQL (mysql2/trilogy) are supported. → openreceive:install

The openreceive:install generator emits three things:

The engine owns the OpenReceivePayment model, so no model file is generated. The engine also 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, on_paid runs at most once per reference. If a second invoice for the same reference is paid, OpenReceive records that payment with status_reason = "duplicate_settlement" and does not fulfill 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 on_paid must be idempotent. The generated initializer explains this and shows the guarded transition:

config.on_paid = lambda do |settlement|
  claimed = Order
              .where(id: settlement.reference, state: "awaiting_payment")
              .update_all(state: "paid", paid_at: Time.at(settlement.paid_at).utc)
  next if claimed.zero? # someone else already fulfilled it

  # FulfillOrder — like Order — is your own application code: ship the goods,
  # enqueue the confirmation email. OpenReceive provides neither.
  FulfillOrder.call(Order.find(settlement.reference), payment_hash: settlement.payment_hash)
end

Delivery is at-least-once. on_paid runs inside the settlement transaction. If it raises, the transaction rolls back and the next pass retries. So keep on_paid to database writes on the order. An email or webhook sent from here would survive the rollback and go out again. The state: "paid" transition above is the flag. Let your own job drain it after commit.

update_all fires no Active Record callbacks. 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 there is no after_commit to attach a post-commit side effect to. That is fine for a background job that drains the flag. It does not help a page that needs to know right away. If you push settlement over Action Cable, or your model owns the transition through callbacks, take a row lock for the duration instead:

config.on_paid = lambda do |settlement|
  order = Order.lock.find_by(id: settlement.reference)   # SELECT … FOR UPDATE
  next unless order && order.state == "awaiting_payment"
  order.update!(state: "paid", paid_at: Time.at(settlement.paid_at).utc)  # callbacks fire
end

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.find_by(id: params[:id], user: current_user, state: "paid"), or a 404 otherwise. The state: "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.

Either way, the rule above still holds: the callback must only make database writes on the order. after_commit on the settlement transaction runs after OpenReceive’s own commit. So an email enqueued there is as safe as one enqueued from a job that drains the flag. An email sent inline from on_paid is not safe, in either shape.

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

Supply the receive-only wallet connection as ENV["NWC_URI"]. Never put it in browser code, logs, or assets. Your application refuses to start when the code advertises spend methods such as pay_invoice. To override that explicitly, set config.allow_spend_capable_wallet = true or OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true (Security).

OpenReceive reads ENV. Rails does not load a .env file on its own, so something has to put the values there first: dotenv-rails, an exported shell environment, or your production secret manager. → Environment variables.

Configure the host hooks

The initializer 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 on_paid 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.

OpenReceive.configure do |config|
  # `Order` throughout is YOUR model — it could be named anything. OpenReceive
  # never sees it or touches its table; these hooks are the only bridge
  # between the engine and your data.
  #
  # Your policy, called before every checkout/payment/swap request. `context`
  # is a Hash with three symbol keys:
  #   context[:action]   — which route: "checkout.prepare", "checkout.create",
  #                        "payment.check", "swap.quote", "swap.create",
  #                        "swap.read", or "swap.refund"
  #   context[:request]  — the ActionDispatch::Request; read your session,
  #                        cookies, or headers from it, 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 nil 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.
  config.authorize = lambda do |context|
    order = Order.find_by(id: context[:resource][:reference])
    order && order.user_id == context[:request].session[:user_id]
  end

  # The price for a reference — here, your order id — from your own data;
  # nil 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.
  config.amount_for = lambda do |reference|
    order = Order.find_by(id: reference)
    order && { currency: "USD", value: order.total.to_s,
               description: "#{order.line_items.size} items" }
  end

  # 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
  # ActiveRecord, because the engine WRAPS this block in the transaction.
  # (The JS engine instead hands onPaid a `query` handle, since nothing wraps
  # it there; that is the one shape difference between the two stacks.)
  config.on_paid = lambda do |settlement|
    claimed = Order
                .where(id: settlement.reference, state: "awaiting_payment")
                .update_all(state: "paid", paid_at: Time.at(settlement.paid_at).utc)
    next if claimed.zero?
  end
end

OpenReceive.configure sets the three host hooks. on_paid runs inside the settlement transaction, only for the first settled attempt for a reference. → OpenReceive.configure

The engine’s controllers inherit from config.parent_controller. The generated initializer sets it to "ApplicationController". That is how the engine picks up your application’s protect_from_forgery. Keep csrf_meta_tags in the layout that renders the checkout. The checkout client sends X-CSRF-Token from it automatically.

The same inheritance also brings every global before_action that your ApplicationController declares. A filter that redirects signed-out users to a login page will redirect the engine’s JSON routes too. A guest checkout then never gets an invoice. The engine reads nothing from the parent except forgery protection. config.authorize receives the request, and your policy reads its own session from it. So if your ApplicationController has such filters, do one of these:

# config/initializers/openreceive.rb (after OpenReceive.configure)
Rails.application.config.to_prepare do
  OpenReceive::ApplicationController.skip_before_action :require_login
end

Keep the filters your authorize policy depends on, such as a tenant resolver or Current attributes. They run before config.authorize.

The generated initializer ships two placeholders. Replace both, not just on_paid:

The amount always comes from your own order record. Payer-supplied amounts are rejected. The advanced hooks resolve_checkout and on_checkout_created remain as overrides for apps with a custom repository. They are not part of the quickstart.

For public web shops, turn on the per-IP invoice cap with config.rate_limiting = true. Leave it off (the default) when many payers share one IP. → 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.

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 that a plain stylesheet link can serve, scoped to what OpenReceive renders.

<%# app/views/orders/pay.html.erb %>
<openreceive-checkout reference="<%= @order.id %>"></openreceive-checkout>

// In your JS bundle (esbuild/webpacker with CSS support):
import { defineElements } from "@openreceive/elements";
import "@openreceive/elements/styles.css"; // or link the compiled styles.css

// Registers the <openreceive-checkout> tag with the browser. Without this,
// the tag in the ERB above 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();

If you bundle with esbuild (jsbundling-rails), build ESM and load it as a module. esbuild’s default IIFE output runs a dependency’s Node fallback in the browser, which throws ReferenceError: __filename is not defined:

esbuild app/javascript/application.js --bundle --format=esm --outdir=app/assets/builds

<%= javascript_include_tag "application", type: "module" %>

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.

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

Reconciliation

Settlement runs on the request path. You do not need a cron job. Disable or tune it with config.opportunistic_reconcile (false, or { min_interval_seconds: … }).

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

bin/rails openreceive:notifications

→ rake openreceive:notifications

To run a pass yourself, use the one-shot OpenReceive.reconcile! or bin/rails openreceive:reconcile. → OpenReceive.reconcile!

Swap secrets

The Ruby server 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 config.swap_providers. Pass your own adapters to replace the auto-built set, or an empty array to disable swaps.

One openreceive_payments row holds at most one provider order, in its server-only swap_data. The engine hides swap_data from Active Record inspection and ordinary serialization. Do not serialize it explicitly, log it, or return it from your own API. 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.