API reference

This page documents each function of the wallet client, the host, the framework adapters, persistence, the CLI, the Rails engine, the Python engine (FastAPI and the openreceive console script) and the PHP engine.

• amount is exactly { sats } or { currency, value }.
• Public results use amount_msats and exact integer or decimal math, never binary floats.
• The spec file spec/openapi/openreceive-http.v1.yaml is the authority for the mounted HTTP routes.

Node and TypeScript APIs return camelCase fields (reference, paymentHash, amountMsats). Mounted HTTP JSON uses the same values in snake_case (reference, payment_hash, amount_msats). Timestamps are integer Unix seconds. Money fields are integers or decimal strings, never binary floats.

Each function lists Input (what you pass) and Returns (what you get back) as separate labeled tables. A nested object, such as a quote, a swap snapshot or a callback argument, gets its own Fields of table. It is not a second input list.

Wallet client

The object createOpenReceive() returns. Examples below call it service.

createOpenReceive

const service = await createOpenReceive(); // reads NWC_URI (and LSC_URI_*) from process.env
// every option below is optional: createOpenReceive({ nwc, allowSpendCapableWallet, swap, … })

Builds the wallet client.

Where it fits: Call this once, when your server starts, and keep the result for the life of the process, the same way you keep a database pool. Every other call in this section is a method on the object it returns. If you use a framework adapter in its all-in-one form, you never call this yourself. Hand the adapter { nwc } and it builds the client for you.

A preflight check runs before the promise resolves. It fails closed, meaning it refuses to start rather than run on a bad setup. It throws ConfigError (MISSING_NWC, INVALID_NWC, WALLET_PREFLIGHT_FAILED) when:

• the NWC URI is missing or invalid,
• the wallet lacks make_invoice or list_transactions,
• the encryption is unsupported, or
• the wallet advertises a spend method and you did not set the override.

The connection string never appears in logs or errors.

Parameters

Returns OpenReceive — the wallet client. Methods:

service.prepareCheckout

const prepared = await service.prepareCheckout({
  amount: { currency: "USD", value: "12.00" }, // or { sats: 21000 }
});

Works out the Lightning amount to charge. It does not mint an invoice or save an attempt.

Where it fits: Use this when the payer lands on your checkout page and you want to show the total in sats, or the coins they could pay with, before they commit to anything. Nothing is minted and nothing is written, so it is safe to call on every page load. Most applications never call it directly. The mounted POST …/checkouts/prepare route wraps it, and the shipped checkout UI calls that route.

The HTTP prepare route uses it so the UI can show the sats total and swap options before create.

Parameters

Returns PrepareCheckoutResult

service.createCheckout

const checkout = await service.createCheckout({
  reference: order.id,
  amount: { currency: "USD", value: "12.00" },
  // optional: memo, descriptionHash, metadata, expirySeconds
});

Mints an invoice that is safe to show the payer.

Where it fits: This is the call for the moment your user clicks “Pay with Lightning” on an order you have already priced. Call it from server-side code only, with the price from your own database. Store the returned paymentHash against the order. That hash is how you check, refund, or resume the attempt later. If you mount an adapter, POST …/checkouts does this for you and also saves the attempt. Call it yourself only when you are building your own route.

On the wire, the same object is the generated snake_case WireCheckout. The browser polls a CheckoutSnapshot, which is its own copy of that wire shape.

The wallet must honor the requested expiry. If the minted invoice’s real payable window differs from expirySeconds by more than 60 seconds, creation fails with a 502 service error. This avoids tracking a row whose reconciliation window is wrong.

This call only talks to the wallet. Saving the attempt happens in the order bridge (createHost).

Parameters

Returns Checkout

RateQuote

The object in fiatQuote on prepareCheckout and createCheckout when you priced in a quoted fiat currency. It is null for { sats } and for Bitcoin units { currency: "BTC" | "SAT" | "SATS", value }. The quote is locked onto the invoice, so later price-feed moves do not change amountMsats. HTTP sends the same object as fiat_quote.

service.reconcilePayments

const checks = await service.reconcilePayments({
  attempts: [{ paymentHash, createdAt }], // one invoice or every pending attempt
  // optional: until, overlapSeconds
});

Looks up known invoices in wallet history.

Where it fits: Use this when you run your own settlement loop, or write an admin tool that asks “has this invoice been paid yet?” for one or many hashes at once. Pass it every pending attempt you have on file and act on what comes back. If you use the host, you don’t need it. reconcileHostPayments calls it for you, writes the outcome back, and fires onPaid.

It reads the wallet in one batch and saves nothing. To check a single invoice, pass a one-element attempts array.

• settled requires settled_at or a wallet transaction state of settled. A preimage alone never proves the payment is final.
• If the scan stops early (is truncated), the hash is left out of the results instead of being reported as not_found. That way a caller cannot close a paid attempt based on an incomplete scan.

Parameters

Returns PaymentCheck[]: one PaymentCheck per decided attempt, in the same order as attempts after hash normalization. The whole batch uses at most two paged list_transactions walks. It never looks up invoices one by one. Hashes the walk could not prove present or absent are left out. Saving results and delivering settlement are the job of reconcileHostPayments.

PaymentCheck

PaymentCheck status

PaymentDetails

Fields of PaymentDetails

OpenReceive differs from the spec in a few names:

• It names the millisatoshi fields amount_msats and fees_paid_msats. The spec says amount and fees_paid.
• It accepts transaction_state as another name for state.

Settlement uses only incoming rows. A positive settled_at, or a state/transaction_state of "settled", means the payment is final. A preimage only supports that evidence and never proves it alone.

service.subscribeWalletNotifications

const unsubscribe = await service.subscribeWalletNotifications((notification) => {
  // called for each payment_received notification
});

Where it fits: This is the low-level way to be told when a payment arrives, instead of polling for it. Use it in a long-running process, not in a web request, and only if you are writing your own listener. Most applications use startNotificationWorker instead. It subscribes for you, marks matching attempts settled, and falls back to a scan when a notification is unclear.

Parameters

The notification argument (not a return value):

Fields of the notification payload

Returns () => Promise<void> | void. Call it to unsubscribe. The promise rejects with OpenReceiveError code UNSUPPORTED_METHOD when the wallet client cannot send notifications. Notifications are authenticated wallet data. Only the type and payment hash are ever logged. How a notification settles an attempt directly is described in startNotificationListener.

service.listSwapOptions

const { enabled, options } = await service.listSwapOptions({
  amountMsats: checkout.amountMsats,
});

Lists whether swaps are configured and the pay-in methods for that amount.

Where it fits: Call this when you are drawing the “how would you like to pay?” screen and need to know whether to show stablecoin buttons at all, and which of them are within the provider’s limits for this amount. It only reads, so call it whenever the amount is known. Over HTTP the same list arrives as payment_methods on the prepare, create, and check responses, so a browser client never needs a separate call.

Automated swaps describes the behavior.

Parameters

Returns ListSwapOptionsResult

Each options[] entry:

Fields of SwapPaymentMethod

service.quoteSwap

const quote = await service.quoteSwap({
  amount: { currency: "USD", value: "12.00" }, // or { sats: 21000 }
  payInAsset: "USDT_TRON",
});

Quotes one pay-in asset for an amount you set. It does not mint an invoice or create a provider order. POST …/swaps/quote calls it.

Where it fits: Use it when the payer has tapped one specific coin and you want to show “send 12.40 USDT” before they commit. Nothing is created at the provider, so it is fine to call as they browse between options. The shipped payment wizard calls the quote route as the payer picks. You only call this yourself when building your own picker.

The result is camelCase. The HTTP handler converts it to the snake_case wire shape.

Parameters

Returns SwapQuoteResult

service.createSwap

const swap = await service.createSwap({
  reference: order.id,
  amount: { currency: "USD", value: "12.00" },
  payInAsset: "USDT_TRON",
  // optional: the createCheckout extras (memo, metadata, expirySeconds, …)
});

Creates a swap attempt: a shadow Lightning invoice plus on-chain deposit instructions. The shadow invoice is the Lightning invoice the swap provider pays on the payer’s behalf.

Where it fits: This is the swap version of createCheckout. Call it at the moment the payer confirms “pay with USDT on Tron” on a priced order. Call it server-side and store the whole result on the attempt row. Send only the PublicSwap fields and the checkout to the browser. The adapters’ POST …/swaps route does exactly that when you mount one.

swapData must stay server-only.

Parameters

Returns SwapCheckout

swapData is { version: 1, providerOrder: SwapOrder }. version is the integer schema version (1). providerOrder holds provider credentials and must stay on the server.

service.getSwap / service.refundSwap

const status = await service.getSwap({ reference, paymentHash, swapData });
const refunded = await service.refundSwap({ reference, paymentHash, swapData, refundAddress });

Both refresh provider state using the swapData you loaded.

Where it fits: Call getSwap when you need the current state of a swap: on a status endpoint the browser polls, or on an admin page. Call refundSwap when a payer asks for their money back after an underpaid or late deposit and you have their refund address. Both need the swapData you saved when the swap was created, so call them from your server. The mounted …/swaps/status and …/swaps/refunds routes do this for you.

refundSwap refuses any provider state other than refund_required.

Parameters

Returns PublicSwap — see PublicSwap below.

PublicSwap

A swap snapshot that is safe to show the payer. It has no provider tokens or credentials.

Fields of PublicSwap (return value of getSwap / refundSwap)

SwapFee

Fiat values attached to a swap for display. The field names follow the provider’s wire shape.

Fields of SwapFee

depositAmount, in the pay-in token, is the only amount a payer is ever told to send. The fee figures are values that explain why it is more than the cart total.

Some stablecoins are pegged to currency (pegged_to in the shared asset table). USDT and USDC are pegged to USD. For these, the packaged checkout shows the breakdown in the token, for example “You send 50.05 USDC” and “Swap + network fees 1.05 USDC (2.1%)”. It never shows pay_in_fiat. A “$50.03” one line under “50.05 USDC” would read as the same number with a typo. Floating assets (SOL, ETH) keep the fiat breakdown.

createSwapFeeBreakdown(fee, swap) applies this rule. Pass it the swap, not just the fee.

service.listRates

const { bitcoin } = await service.listRates(); // or ({ currencies: ["USD", "EUR"] })

Where it fits: You’ll use this for display, not for pricing: a “1 BTC = $65,000” footer, a currency switcher, a rough sats preview before an order exists. When it is time to charge, price the order with prepareCheckout or createCheckout instead. They lock the quote onto the invoice. A rate you read here can move before the payer pays.

Parameters

Returns { bitcoin }

The wallet client also has quoteRates. It is the internal helper that builds the fiatQuote that prepareCheckout / createCheckout attach. It exists only in JS, with no HTTP route and no Ruby counterpart. Use prepareCheckout to quote an amount.

service.close

await service.close();

Returns Promise<void>. Closes the underlying wallet client and its relay connection. If you run the notifications worker, stop it first.

Where it fits: At the end of a script, a one-off job, or a test, after the last wallet call. A long-running server can usually skip it, as explained below.

The wallet client is only created on the first wallet call. So close() does nothing for a wallet client that never minted or scanned.

Call it in scripts, one-shot jobs, and tests. An open relay connection keeps the Node event loop alive. A process that skips close() finishes its work and then hangs instead of exiting.

A long-running server does not need it. No payment state lives in memory. The wallet plus the payments table hold the truth about settlement, and there is no queue to drain. So a process that is terminated loses nothing by skipping it. The Express middleware and the Next handler still expose close() if you want a predictable shutdown on SIGTERM. The Fastify plugin registers an onClose hook and closes with the app.

Host (@openreceive/http)

The object createHost() returns. It connects OpenReceive to your application: your price, your fulfillment, and your database. By convention it is held in a variable named host.

createHost

const host = createHost(options: CreateHostOptions): Host

Where it fits: Write this once, next to where you build the wallet client. It is where your own code plugs in: amountFor looks up the price, onPaid marks the order paid, and db is the database connection you already have. Pass the result to an adapter or to the reconcile functions. With an adapter in all-in-one form, you give the adapter the same three things and it calls createHost for you.

In the default db mode, OpenReceive owns the openreceive_payments rows inside your application’s existing database.

Parameters

onPaid

In db mode, onPaid receives a PaymentSettlement. This is the callback’s argument, not a return value.

Fields of PaymentSettlement

onPaid runs inside the settlement transaction, and only for the order’s first settled attempt. It is write-once: a second settled attempt for the same order records duplicate_settlement and never fulfills again. Delivery is at-least-once. If onPaid throws, the transaction rolls back and the next reconciliation pass retries.

Write through the supplied query. It is the only handle inside the settlement transaction. An ORM call made here uses that ORM’s own connection, so it commits separately. It can survive a rolled-back settlement, or be lost when settlement commits and it does not.

On Rails this handle does not exist, and that is on purpose. The Rails engine wraps the on_paid block in an ActiveRecord transaction. Plain ActiveRecord inside the block is already part of that transaction, so there is nothing to pass through. PaymentSettlement there carries reference, payment_hash, paid_at and details, and no query. If you port between the engines, you only need to know which side supplies the transaction. JS hands you a handle. Rails wraps your block.

Keep onPaid to database writes. Anything that reaches outside the transaction, such as an email, a webhook, or a shipping call, survives a rollback and runs again on the retry. Flag the order here, or insert the outbox row shown below, and let your own worker process it after commit. There is no after-commit hook, by design.

onPaid: async ({ reference, query }) => {
  await query("UPDATE orders SET state = 'paid' WHERE id = ?", [reference]);
  // Same transaction: enqueue follow-up work here rather than doing it inline.
  await query("INSERT INTO outbox (kind, reference) VALUES (?, ?)", ["order_paid", reference]);
},

If your ORM can run statements on a connection you pass it, wrap query. Node ORM recipes has a recipe for each ORM.

As an advanced escape hatch, you can replace db with a full repository implementation.

Parameters

Returns Host, for the framework adapters and reconcile passes. The attempt row commits before the payer sees any payment instructions.

• If the repository refuses the commit (an already-paid order, or a competing live attempt), the response is 409.
• If the commit fails because of infrastructure, the response is a retryable 503.

Either way the invoice is withheld.

CheckoutCreatedInput

Passed to onCheckoutCreated after the wallet mints and before the HTTP response is written. If it refuses by throwing a 409-shaped error, the response is 409. Any other throw becomes a retryable 503. In both cases the payer gets no payment instructions.

Fields of CheckoutCreatedInput (argument to onCheckoutCreated)

The authorize context

Every route that acts on an order calls authorize(context) before any wallet or database work. Returning false produces 403 FORBIDDEN. The optional rateLimitHook uses the same shape. It returns false for a 429.

Where it fits: You write authorize where you would write a controller’s “is this their order?” check: look up resource.reference in your data, compare it with whoever is logged in on request or native, and return a boolean. Every payment route runs it first, so this one function is your whole access policy for OpenReceive.

There are two deliberate exceptions:

• GET …/rates has no order, so it is never authorized.
• The opportunistic reconcile pass runs before authorization. This is the settlement check that runs on ordinary requests, limited by a durable gate in the database. It reads only OpenReceive’s own attempt rows and the wallet, and the gate limits how often it runs.

There is one callback type: (context: AuthorizeContext) => boolean | Promise<boolean>. Some snippets destructure { native, resource } or { action, request, resource }. These are not other signatures. They just name the fields they read. Sync and async returns both fit this type.

Fields of AuthorizeContext (argument to authorize, not a return value)

An Express session example. It is the same callback, reading native instead of request:

authorize: ({ action, request, resource, native }) => {
  const userId = (native as { session?: { userId?: string } }).session?.userId;
  return userId !== undefined && orders.belongsTo(resource.reference, userId);
},

startReconciler

const reconciler = await startReconciler({
  service,
  host,
  // optional: pollIntervalMs, overlapSeconds, signal, clock, onError
});

Where it fits: Use this only when you want a background loop that scans the wallet on a timer and nothing else, for example on a wallet that cannot send notifications. Most applications skip it: the request-path pass settles orders as payers poll, and the notifications worker already includes this loop.

It is a basic polling loop. startNotificationWorker uses it internally, and you can call it directly, but no adapter or stack starts it. Most applications rely on the default opportunistic reconcile that runs on requests (maybeReconcilePayments) and never call this.

Parameters

Returns Reconciler. Every pass goes through the durable reconcile gate (maybeReconcilePayments). So any number of reconciler instances, plus the opportunistic reconcile on requests, share one real wallet scan per gate interval. Construction throws unless the repository implements claimReconcileGate and checkpointReconcileGate.

A failed pass is reported and retried from the ledger, so delivery is at-least-once. Only pending attempts are scanned. Settled and closed rows leave the scan set. This keeps the scan window small without a saved cursor.

reconcileHostPayments

const checks = await reconcileHostPayments({
  service,
  host,
  // optional: overlapSeconds, maxPages, clock
});

Where it fits: This is the one-shot call: check everything pending and fulfill what settled. Use it from a cron job, a script, or an admin button when you want a pass now and want the results back. The gated pass and the worker call it for you, so it rarely belongs in a normal request.

It runs one pass with a fixed limit. Each pass:

1. Lists the oldest pending attempts, up to OPENRECEIVE_RECONCILE_BATCH_SIZE (200). A backlog drains over several passes.
2. Scans the wallet once for the whole batch. maxPages caps the paged walks.
3. Delivers settlements through host.onPaid. Delivery is at-least-once, and the repository makes it write-once.
4. Saves final state changes.
5. Returns the PaymentCheck result for each hash in the pass.

Like every OPENRECEIVE_* name in this section, OPENRECEIVE_RECONCILE_BATCH_SIZE is a constant exported by @openreceive/http, not an environment variable.

To close an unpaid attempt, a wallet scan must succeed at or after expiry plus the 900-second grace (OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS). The local clock alone never closes a row. A settled result without paidAt is retried on the next pass. On a wallet or repository failure it throws and leaves every row pending for the next pass.

maybeReconcilePayments

const result = await maybeReconcilePayments({
  service,
  host,
  // optional: minIntervalSeconds, scanTimeoutMs, maxPages, overlapSeconds, clock, onError
});

Where it fits: Call this from routes of your own that a waiting payer hits, such as a custom order-status endpoint, so settlement gets a chance to run there without a separate worker. It is cheap to call often: it does nothing when nothing is pending, and the durable gate makes many web instances share one wallet scan. The mounted routes already call it, so you only add it where you have built your own.

Parameters

This is the gated pass behind the handler’s default opportunistic reconcile on requests. It is exported so you can drive settlement from your own routes or middleware. Your own routes never run it automatically. It works like this:

1. If nothing is pending, it skips without calling the wallet.
2. It claims the durable openreceive_meta gate. The claim is an optimistic compare-and-swap (CAS) shared by every instance on your database. gate_busy means another worker just scanned.
3. Otherwise it awaits one bounded reconcileHostPayments pass.

It never throws. A failed scan reports to onError and returns scan_failed. The gate’s claim stays in place, so a broken wallet cannot trigger a flood of retries. A page still in flight at the 9 s scan deadline is cut: when earlier pages answered, the pass returns ran and the next pass resumes after them; when none did, the pass fails like any other wallet failure.

Returns { reason: "ran", checks } (the per-hash PaymentCheck results) or { reason: "no_pending" | "gate_busy" | "scan_failed" }.

startNotificationListener

const listener = await startNotificationListener({
  service,
  host,
  // optional: overlapSeconds, onError
});

Where it fits: Use it when you already run your own periodic reconcile and only want the notification part: one long-running process that settles an order the moment the wallet announces the payment. If you don’t have that loop, use startNotificationWorker, which does both.

Parameters

Returns NotificationListener

Most applications use startNotificationWorker instead. It wraps this listener plus the periodic pass.

This is an opt-in NWC-02 listener that can settle attempts directly. Notifications are authenticated wallet data. So a payment_received payload settles its attempt directly through host.onPaid, with no wallet scan for that invoice, when both of these hold:

• it meets the settlement rule: settled_at or a settled transaction state, never a preimage alone, and
• it matches a pending attempt.

Settling removes the attempt from the pending set, so no later pass scans it again.

Anything less wakes one gated pass (maybeReconcilePayments). That covers no payload, no sign that the payment is final, or a hash that is unknown or not pending. A burst of notifications queues at most one follow-up pass. A pass that another worker just ran is not repeated.

If direct settlement fails, it reports to onError and falls back to a scan. A periodic pass, either the worker’s or the opportunistic reconcile on requests, remains the safety net for notifications missed while offline.

Direct settlement assumes the NWC client ties notification decryption to the connection’s wallet pubkey. The bundled SDK does this. Do not allow direct settlement for a custom client that skips author verification.

startNotificationWorker

const worker = await startNotificationWorker({
  service,
  host,
  // optional: pollIntervalMs, overlapSeconds, onError
});

Where it fits: Run this when you want orders marked paid within a second of the payment arriving, instead of on the payer’s next poll. Put it in a small script of its own and run it as a separate process next to your web server, for example a worker line in your Procfile. Stop it before you call service.close(). It is optional. A web deployment with no worker still settles every order through the pass that runs on requests.

Parameters

The worker is optional. It is one separate long-lived process that runs two things:

• the notification listener, which settles directly when a payment is final and otherwise runs one pass, and
• the periodic reconcile pass, the safety net for notifications missed while the worker was down.

Every scan it takes goes through the same durable reconcile gate as the pass on requests. So the worker plus any number of web instances still share one wallet scan per interval. If the wallet does not support notifications, the worker falls back to the periodic pass alone and reports this through onError.

There is deliberately no npx openreceive notifications CLI, because the CLI cannot see your onPaid or database. Start the worker from a small script of your own.

Returns NotificationWorker

Settlement entry points

Settlement arrives in two ways:

• The opportunistic reconcile pass on requests. This is the default. Any mounted payment route runs it, gated by the durable openreceive_meta row. The unauthenticated GET …/rates never triggers it, so crawlers and health checks cannot use up the wallet-scan budget.
• The optional notifications worker.

POST /payments/check never walks the wallet for its own invoice. It uses the result of the request’s pass.

• If this request won the gate, it serves status/paid_at/details straight from the pass. Settlement was already delivered inside the pass.
• On gate_busy, or with opportunistic reconcile disabled, it serves the stored row without details. A row in attention shows as pending on the wire.

Both paths are safe to replay, because they share the same write-once path. onPaid still runs inside the web request when that request wins the pass. So fulfillment work must be safe to run inside a web request. Keep it transactional, or enqueue an outbox job.

Framework adapters

All three adapters serve the route set in the OpenAPI spec and accept two forms of options.

Each adapter re-exports only a chosen part of @openreceive/http: the handler and stack factories, their options, context and hook types, the error classes, the notification worker, and the generated Wire* body types. The order-bridge internals (createSqlPayments, the reconcile gate, createHost, rate-limit internals) live only in @openreceive/http. Import them from there when you compose your own integration. npm run check:public-api locks these surfaces.

All-in-one form (the usual path): order hooks plus wallet and storage. The adapter builds the wallet client and host itself. Startup waits until the first request, which awaits the wallet preflight. The Express middleware and the Next handler expose ready (a promise) and close() (closes the wallet client they own). The Fastify plugin exposes neither. It registers an onClose hook that shuts the stack down with the app.

Parameters

Composed form (CreateHttpHandlerOptions), for shared wallet clients, custom repositories, and tests:

Parameters

The same all-in-one form is available without a framework as createStack(options) in @openreceive/http. It returns { handler, ready, close }.

Create routes reject amounts sent by the payer and take the price from amountFor. Payment and swap reads take reference plus payment_hash. After your authorization passes, the library checks that this exact attempt belongs to the order and supplies the server-only swap_data.

HTTP JSON is snake_case. The values are the same as the Node objects above. The table below is generated from the OpenAPI contract, which is the authority. … is the mount prefix (default /openreceive).

| Route | Status | Response body | | — | — | — | | POST …/checkouts/prepare | 200 | PrepareCheckoutResponse { reference, amount_msats, description?, fiat_quote?, payment_methods } | | POST …/checkouts | 201 | CreateCheckoutResponse { checkout: Checkout, description?, payment_methods } | | POST …/payments/check | 200 | PaymentCheck { payment_hash, status: PaymentStatus, paid_at?, details?: PaymentDetails, payment_methods } | | POST …/swaps/quote | 200 | SwapQuote { provider, pay_asset: SwapPayInAsset, available, pay_amount?, minimum_pay_amount?, maximum_pay_amount?, minimum_invoice_amount_msats?, maximum_invoice_amount_msats?, unavailable_reason?, unavailable_message? } | | POST …/swaps | 201 | CreateSwapResponse { swap: SwapCheckout } | | POST …/swaps/status | 200 | Swap { payment_hash, reference, provider, pay_in_asset: SwapPayInAsset, deposit_address, deposit_memo?, deposit_amount, provider_state: SwapProviderState, provider_expires_at, deposit_tx_id?, payout_tx_id?, refund_tx_id?, refund_reason?, refund_amount?, attention?, attention_reason?, deposit_received_amount?, emergency_repeat?, provider_order_id?, fee?: SwapFee } | | POST …/swaps/refunds | 200 | Swap { payment_hash, reference, provider, pay_in_asset: SwapPayInAsset, deposit_address, deposit_memo?, deposit_amount, provider_state: SwapProviderState, provider_expires_at, deposit_tx_id?, payout_tx_id?, refund_tx_id?, refund_reason?, refund_amount?, attention?, attention_reason?, deposit_received_amount?, emergency_repeat?, provider_order_id?, fee?: SwapFee } | | GET …/rates | 200 | RatesResponse { bitcoin } |

How the bodies map to the Node objects above:

• POST …/checkouts returns Checkout in snake_case (the generated WireCheckout).
• POST …/checkouts/prepare returns the prepare result plus swap options.
• POST …/payments/check returns PaymentCheck plus payment_methods. This is the same swap-option list. It is empty when Lightning is the only payment rail. It comes from a 60-second cache inside the handler, so status polls every ~3s do not walk the provider catalog on every request.
• POST …/swaps/quote returns the snake_case quote (provider, pay_asset, available, pay_amount?, limits).
• POST …/swaps returns PublicSwap plus a nested checkout, with swap_data removed.
• …/swaps/status and …/swaps/refunds return the bare snake_case PublicSwap object, with no { swap } wrapper. Only POST …/swaps wraps it.
• GET …/rates returns { bitcoin: { <currency>: "<price>" } }.

Repeating a create: mint, or re-serve

POST …/checkouts and POST …/swaps do not always mint. A request mints only when the order has no saved attempt it can serve again. Otherwise it answers with the attempt the order already has. That means no wallet call, no provider order, no second row, and no rate-limit charge. This makes a reload, a back button, or a payer picking the same coin again safe. They get their own deposit instructions back, not a second address to send to.

Serving the old attempt again has conditions. Know them before you build resume on top of it. The attempt must be:

• unpaid and live,
• on the same payment rail (and, for a swap, the same pay_in_asset), and
• more than 60 seconds before its own expiry.

Past that point, the same call mints a replacement: a fresh BOLT11, or a fresh deposit address. A swap’s expiry is the expiry of its shadow Lightning invoice. The provider sizes that invoice to outlast its deposit window, roughly half an hour with FixedFloat’s defaults. So a payer returning the next day gets a new attempt rather than their old one. Two live attempts on the same rail for one reference is a 409 CONFLICT.

POST …/swaps/status has no such window. It takes { reference, payment_hash } and addresses that one attempt directly. So it still answers for an attempt that stopped being payable hours ago. That makes the payment hash, not the chosen asset, the lasting handle for bringing a payer back to a deposit or refund screen. See Swap refunds → The way back.

Errors

The error body and the per-route error statuses are generated from the spec. 429 responses also carry a Retry-After header. Both engines answer two statuses before authorize runs:

• 415 for a body that is not application/json, and
• 403 for a request the browser labels Sec-Fetch-Site: cross-site. See Cross-site requests.

Every error status above returns the OpenReceive error body { code, message, retryable?, request_id?, details? } (normative: spec/schemas/error.schema.json). code is one of:

NOT_IMPLEMENTED, RESTRICTED, UNAUTHORIZED, FORBIDDEN, RATE_LIMITED, QUOTA_EXCEEDED, INTERNAL, UNSUPPORTED_ENCRYPTION, OTHER, NOT_FOUND, TIMEOUT, INVALID_REQUEST, WALLET_UNAVAILABLE, INVOICE_EXPIRED, UNSUPPORTED_METHOD, CONFLICT

| Route | Declared error statuses | | — | — | | POST …/checkouts/prepare | 400, 403, 404, 405, 413, 415, 429, 500, 503 | | POST …/checkouts | 400, 403, 404, 405, 409, 413, 415, 429, 500, 502, 503 | | POST …/payments/check | 400, 403, 404, 405, 409, 413, 415, 429, 500, 502, 503 | | POST …/swaps/quote | 400, 403, 404, 405, 413, 415, 429, 500, 503 | | POST …/swaps | 400, 403, 404, 405, 409, 413, 415, 429, 500, 502, 503 | | POST …/swaps/status | 400, 403, 404, 405, 413, 415, 429, 500, 502, 503 | | POST …/swaps/refunds | 400, 403, 404, 405, 409, 413, 415, 429, 500, 502, 503 | | GET …/rates | 400, 405, 500, 501, 503 |

Error codes: who retries, and whose bug

The body includes retryable when it differs from the code’s own default. Use the “Whose bug” column to decide where an error goes. A yours row belongs in your error tracker. A payer row does not.

Status vocabularies: who sees which

Six different “status” vocabularies appear across the stack. They are NOT the same set of values, and each has exactly one audience.

deriveStatus(invoice) gives the browser’s one-word verdict for an attempt: pending, settled, expired or failed. These are the payment check’s words minus not_found, because a snapshot always has an attempt. It comes from the server’s transaction_state. The browser never works out “settled” from settled_at itself.

openReceiveExpress

app.use(openReceiveExpress(options)): ExpressMiddleware

Express middleware. It handles requests under its prefix and calls next() for everything else. The original Express req is passed as native.

Where it fits: This is the one line that puts OpenReceive in an Express app. app.use(...) it once at startup, before your 404 handler, and every checkout, status, swap, and rates route exists under /openreceive. Put your session middleware ahead of it so authorize can read native.session.

openReceiveFastify

await fastify.register(openReceiveFastify, options)

Fastify plugin. It registers a catch-all route under prefix. The original Fastify request is passed as native. Options are the shared all-in-one or composed set above, plus trustProxyIpHeader.

• Pass prefix at register() so Fastify scopes the route to it. A prefix that disagrees with the register scope fails registration.
• Fastify parses JSON itself, so there is no body parser to add.
• Behind a reverse proxy, Fastify({ trustProxy: true }) makes request.ip the payer’s IP. This is the same rule as Express’s trust proxy.

Where it fits: Register it once during app setup, after whatever plugin gives you sessions or auth decorations, because authorize sees the same request object. Shutdown is handled for you. The plugin closes the wallet client with the app. Full walkthrough: Fastify quickstart.

openReceiveNextHandlers

export const { GET, POST } = openReceiveNextHandlers(options)

Next.js App Router handlers. Mount them as a catch-all route (app/openreceive/[...openreceive]/route.ts) that exports runtime = "nodejs" and dynamic = "force-dynamic". The incoming NextRequest is passed as native. Options are the shared all-in-one or composed set above, plus trustProxyIpHeader. Here trustProxyIpHeader is required when you use rateLimiting, because a web Request has no socket IP (Rate limiting). Full walkthrough: Next.js quickstart.

Where it fits: Create one catch-all route file, export what this returns, and the whole route set is live. Keep it on the Node runtime, not the Edge runtime, because it needs your database driver and a relay connection. Read cookies or headers from request inside authorize the way you would in any route handler.

Returns the App Router handler object

Persistence

createSqlPayments

const payments = createSqlPayments(db, options?): SqlPaymentRepository

Where it fits: You’ll only call this directly in the composed form, when you want to hold the repository yourself: to look at attempts with listForReference in an admin tool, or to share one repository between a host and a test. createHost({ db }) builds it for you otherwise.

Parameters

This is the repository the library owns behind createHost({ db }), exposed for advanced integrations. It is responsible for:

• locking commits per reference (SQLite BEGIN IMMEDIATE, postgres advisory lock),
• deciding whether a new attempt replaces a live one or conflicts with it,
• the pending → settled | expired | failed | attention state machine, and
• markPaidOnce, the settlement transaction that is safe to replay. It fulfills only the order’s first settled attempt and never overwrites a settled row.

Returns SqlPaymentRepository

A custom PaymentRepository must also implement claimReconcileGate and checkpointReconcileGate, unless you pass opportunisticReconcile: false. Both must be durable CAS operations. Never use an in-process cooldown, because memory cannot coordinate separate workers. Handler construction throws if they are missing.

paymentsSchemaSql

paymentsSchemaSql(dialect: "postgres" | "sqlite", tableName?, metaTableName?): string

Where it fits: Use this when writing the migration that creates OpenReceive’s two tables in your own migration tool. Call it and execute the string it returns. If you use one of the supported ORMs, npx openreceive scaffold payments writes the same DDL in that ORM’s migration format instead.

Parameters

Returns string: the DDL for two tables in that dialect.

• openreceive_payments holds the attempts, with its indexes.
• openreceive_meta holds the reconcile gate (key TEXT PRIMARY KEY, value TEXT NOT NULL, rev). It starts with a schema_version row.

tableName and metaTableName rename them. The statements themselves live in @openreceive/core (paymentsDdlStatements in payments-ddl.ts). This helper and the scaffold CLI’s ORM migrations are both built from that one source. Run it through your own migration workflow. The scaffold CLI wraps it per ORM. Keep every column and constraint. payment_hash is globally unique. reference is indexed, not unique.

SqlAdapter

The database interface to implement yourself when the built-in pg/SQLite bindings do not fit.

interface SqlAdapter {
  dialect: "postgres" | "sqlite";
  query(sql: string, params?: readonly unknown[]): Promise<readonly Record<string, unknown>[]>;
  transaction<T>(run: (tx: { query }) => Promise<T>): Promise<T>;
}

Where it fits: You implement this when your database access goes through something the library does not know: a driver it has no binding for, a connection wrapper of your own, or an ORM without a named factory below. It has two methods, and the rules are simple: pass the SQL through unchanged, and make transaction a real transaction. Check the ORM factories first. Most people never write one.

query receives each statement already written for the adapter’s declared dialect (? on sqlite, $1-style on postgres). It must pass the statement to the driver EXACTLY as given. Nothing rewrites placeholders, in either direction. It returns SELECT rows (Record<string, unknown>[]), or [] for a non-SELECT. transaction must be truly atomic. Write-once settlement and fulfillment both run inside it.

knexDb / prismaDb / typeOrmDb / sequelizeDb

createHost({ db: knexDb(knex, "postgres") });        // or prismaDb(prisma, …),
createHost({ db: typeOrmDb(dataSource, "sqlite") }); // sequelizeDb(sequelize, …)

Ready-made SqlAdapter factories for the ORM handles that createSqlPayments cannot accept directly.

Where it fits: Pick the one that matches your ORM. Pass its result as db wherever you would have passed a pg pool, right where you build the host, using the ORM handle your application already shares. That is all the persistence wiring you need.

The parameter types (KnexLike, PrismaLike, TypeOrmLike, SequelizeLike) only describe the shape they need, so no ORM dependency is added. dialect (SqlDialect) is required, because nothing on the handles states it reliably. Each factory handles its ORM’s raw-query quirks:

• knexDb normalizes the result shape, which differs per driver.
• prismaDb sends each statement to either $queryRawUnsafe or $executeRawUnsafe. A statement with RETURNING counts as one that returns rows.
• typeOrmDb queries through the transaction’s own EntityManager.
• sequelizeDb binds parameters through bind and passes the managed transaction into every statement inside it.

See Node ORM recipes for the wiring guide.

PaymentRecord

One openreceive_payments row as returned by payments.listForReference.

Fields of PaymentRecord

Browser & React

These are the browser and React pieces you wire up. The Vue, Svelte and Angular wrappers hand off to the same custom element and accept the same attributes.

prefix is the only URL input the browser packages take. It is the base path where the shipped router is mounted. Every route they call is built from it: /checkouts, /checkouts/prepare, /payments/check, /swaps, /swaps/quote, /swaps/status, /swaps/refunds. There is no per-route override, so a checkout cannot be created against one mount and settled against another.

Failed status polls wait longer after each failure (exponential backoff) and honor the server’s Retry-After. Network and HTTP failures are thrown as BrowserRequestError, carrying status/code/retryable/retryAfterSeconds.

prepareCheckout

From @openreceive/browser: prepareCheckout({ reference, prefix, fetch?, headers? }). Calls POST /checkouts/prepare. It locks the amount and returns payment methods without minting.

requestCheckout

From @openreceive/browser: requestCheckout({ reference, prefix, fetch?, headers?, memo?, metadata?, previous? }). Calls POST /checkouts. It mints (or reuses) a bolt11 and returns the snapshot.

The response echoes payment_methods alongside checkout (contract 0.4.1). So the list of pay-in methods survives a mint on its own, for any client, not just this package.

Pass previous when you drive the prepare-then-mint flow yourself and want the snapshot to carry over. previous is the snapshot already on screen, normally what prepareCheckout returned. It carries sibling attempts, such as a live swap next to the new bolt11, that the mint response knows nothing about. It also still carries the method list forward against a server older than 0.4.1. The shipped renderers do this for you.

<Checkout>

From @openreceive/react. A complete checkout in one component. It has two modes:

• Create mode: pass reference + prefix.
• Snapshot mode: pass checkout, plus prefix for polling. prefix defaults to /openreceive, so a bare snapshot still polls.

polling={false} renders without status polling and keeps the swap flow working.

Common props:

• the seven handlers: onCopy, onOpenWallet, onState, onSettled, onProviderCopy, onStartOver, onError
• polling, pollIntervalMs, paymentWizard
• theme: a lock set by your app. It wins over the stored preference and hides the toggle.
• themeToggle: default true. false hides the control, but the checkout still sets data-theme.
• defaultTheme, storageKey, decodeLinkUrl, csrfHeader, components, classNames, syncUrl, resumePathPrefix, routeReference, resumable, resumePaymentHash, metadata, createFetch

There is no image prop. Everything the checkout draws ships inside the JavaScript (Provider registry).

csrfHeader (default X-CSRF-Token) is the header name used to send the page’s <meta name="csrf-token"> value on every request. Rails and Laravel read the default. Django reads X-CSRFToken. WordPress REST reads X-WP-Nonce. The meta tag name is fixed.

resumePaymentHash (create mode) names a swap attempt this order already has in progress. The checkout reopens it after prepare instead of showing the method grid. A hash that cannot be served is ignored.

resumable says whether a payer who closes this tab has a URL that brings them back. It is inferred from syncUrl / routeReference. Set it explicitly when your own router owns a per-order route. It picks which return warning the swap refund screen shows (SwapDisplayModel.refundReturnLabel). See Checkout UX → The refund screens.

Some props are shared with the Vue, Svelte and Angular wrappers, with the same names and defaults. These are everything in the list above up to and including csrfHeader, except theme, plus checkout and reference.

• theme is a React-only prop. The custom element carries the same lock as its theme attribute.
• components, classNames, children and createFetch are React-only, with no wrapper equivalent.
• polling / pollIntervalMs reach the wrappers only through their options escape hatch.

docs/internal/wrapper-parity.md has the full table.

children is React-only. It is a node, or a render prop that receives the live useCheckout model. Use it for order context, such as a line-item summary, a thumbnail, or a “you are buying” strip. The checkout shows the amount but never the order, so without it that context is missing. Children appear above the shipped payment UI, where the custom element’s order slot sits, and never replace it. See Frontend checkout → Show the payer what they are buying.

useCheckout

From @openreceive/react: useCheckout(options). The hook behind <Checkout>, for custom layouts. It drives a concrete checkout snapshot. Create mode belongs to <Checkout>. Unlike the component, it does not default prefix. Pass prefix to poll /payments/check. Omit it, or pass polling: false, to render the snapshot without polling. It returns the live snapshot, status, countdown labels, statusTitle/statusDetail, and copyInvoice/openWallet/reloadState/retry/cancel.

openWallet is for touch devices. By default it calls location.assign on the current window. On desktop, a wallet button either does nothing or takes the payer away from a checkout that is still polling. That is why <Checkout> renders no wallet button and offers components.OpenWalletButton as an opt-in slot. See Headless checkout.

PaymentWizard

From @openreceive/react. The method picker and swap deposit flow shown inside <Checkout>. You can use it on its own with checkout, prefix, and onSwapStarted. If you omit prefix, it renders only the method grid, because it has no swap backend to call.

<openreceive-checkout>

From @openreceive/elements. The custom element behind the non-React wrappers.

• Create mode: reference + prefix attributes.
• Snapshot mode: invoice/invoice-id/payment-hash/… attributes.
• Polling: polling="false" renders without status polling. poll-interval-ms sets the interval.
• csrf-header names the header used to send the csrf-token meta value. Default X-CSRF-Token. Django uses X-CSRFToken, WordPress REST uses X-WP-Nonce.
• The way back to a refund: sync-url, resume-path-prefix, route-reference, resumable and resume-payment-hash. They behave like the React props of the same names, above. See Frontend checkout → The way back to a refund.

There is no asset attribute. Everything the element draws ships inside its JavaScript. It fires seven events: openreceive-copy, openreceive-open-wallet, openreceive-state, openreceive-settled, openreceive-provider-copy, openreceive-start-over, openreceive-error. openreceive-state and openreceive-settled carry the checkout snapshot at event.detail.state.

CLI

openreceive scaffold payments

npx openreceive scaffold payments [options]

Writes one schema or migration file for your ORM, plus an OPENRECEIVE_PAYMENTS.md wiring guide. The file creates two tables: openreceive_payments (the payment attempts) and openreceive_meta (the reconcile gate). It does nothing else. It never opens a database connection or runs migrations.

Where it fits: Run it once, at the start of the integration, from the directory that holds your ORM’s migrations. Then apply the migration the way you apply your own. Commit the generated file. You will not run this again unless you change table names.

Every generated file includes the note about fulfilling each order exactly once.

openreceive doctor

npx openreceive doctor
npx openreceive doctor --db db/production.sqlite3 --url http://localhost:3000

Checks the server configuration and says what to fix.

Where it fits: Run it first, before writing any code, on the machine the app will run on, and again whenever a deploy misbehaves. Run it when the payment page says the wallet is unavailable and you don’t know why. Once the app is up, add --db and --url to check the tables and the routes too.

It always checks:

• the Node version and working directory,
• whether NWC_URI is set and can be parsed (printed with secrets hidden), and
• the LSC_URI_* connections.

When NWC_URI parses, it also probes the wallet over the relay, the same preflight that runs at boot. It reports whether the code is receive-only. --offline skips the probe. No database is touched by default.

The exit code is 1 when any check fails. Every failing line states its own fix. openreceive debug-report prints the same lines as a support report with secrets hidden, and always exits 0.

Rails

openreceive:install

bin/rails generate openreceive:install

Creates three things:

• one migration, db/migrate/*_create_openreceive_tables.rb, which creates both openreceive_payments and the openreceive_meta reconcile gate,
• a simplified config/initializers/openreceive.rb, and
• the engine route mount at /openreceive.

Where it fits: Run it once right after adding the gem, then bin/rails db:migrate. The rest of the integration goes in the files it creates. The three hooks below go in the initializer, and the browser packages point their prefix at the mount.

The migration adapts to the app’s configured database adapter. PostgreSQL, SQLite, and MySQL (mysql2/trilogy) are supported. The engine owns the OpenReceivePayment model, so no model file is generated.

The generated initializer ships two placeholders:

• config.on_paid = OpenReceive::LOGGING_ON_PAID only logs and fulfills nothing.
• config.authorize = OpenReceive::ALLOW_ALL_AUTHORIZE allows every request. Anyone who has the reference is treated as authorized, which is safe only while references cannot be guessed.

The engine warns every time your application boots while either is still configured. Replace both before anything real.

OpenReceive.configure

OpenReceive.configure do |config| ... end

Where it fits: This lives in config/initializers/openreceive.rb and runs at boot. It is the only place your application and OpenReceive meet. authorize is your “is this their order?” check, amount_for is your price lookup, and on_paid is where you mark the order paid. Everything else in the engine is generic. These three hooks are the integration.

Three hooks are required: authorization, the trusted price, and fulfillment. There are also a few optional settings.

OpenReceive.configure do |config|
  # `Order` in these examples is YOUR model — any name works. OpenReceive
  # never sees it; these hooks are the only bridge into your data.

  # REQUIRED. Your policy, called before every checkout/payment/swap route.
  # `context` is a Hash with three symbol keys:
  #   context[:action]   — which route, as a String: "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: } on every action, plus
  #                        { payment_hash: } on payment.check, swap.read, and
  #                        swap.refund. Copied from the payer's JSON body
  #                        before any lookup: it names an order, it does NOT
  #                        prove this caller may touch it. reference is always
  #                        a validated non-empty String (≤200 chars);
  #                        payment_hash is nil on the other four actions.
  # Return true to allow, false for a 403. Look the order up in YOUR data and
  # decide whether THIS caller may perform THIS action 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

  # REQUIRED. The trusted price for a reference (your order id). Return
  # { currency: "USD", value: "12.00" } or { sats: 1200 } (string keys work
  # too), or nil when there is nothing to pay for (a 404). Called only where a
  # price is minted or quoted; payer input never carries an amount.
  #
  # An optional "description" beside the price is what the payer is buying, in
  # your own words: one display string, echoed on the prepare and create
  # responses, rendered above the amount by both drop-ins, and used as the
  # invoice memo so the payer's wallet shows it too. The checkout shows a total
  # and never an order, so without it the payer sees a QR and a number.
  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

  # REQUIRED. Fulfillment. Runs inside the settlement transaction, only for
  # the first settled attempt for a reference. `settlement` responds to:
  #   settlement.reference    — your order id that just settled (String)
  #   settlement.payment_hash — 64-char lowercase hex hash of the attempt
  #   settlement.paid_at      — Unix seconds of settlement (Integer)
  #   settlement.details      — wallet-observed details Hash (transaction
  #                             snapshot, observed_at, paid_at_source — the
  #                             same shape JS delivers to onPaid), or nil
  # There is deliberately no `query` handle here: the engine wraps this block
  # in an ActiveRecord transaction, so plain ActiveRecord IS the transactional
  # write. (The JS engine hands `onPaid` a `query` because nothing wraps it
  # there.) Same rule as JS otherwise: database writes only — anything
  # reaching outside the transaction survives a rollback and runs again.
  # The WHERE clause is the lock: a second fulfillment path of yours (admin
  # action, replayed job) claims zero rows and does nothing.
  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
  end

  # Per-IP invoice cap for public web shops. Off by default — never throttle
  # a shared-IP POS terminal by accident. `true` caps invoice creation at 60
  # per client IP per rolling hour, counted from the engine-owned
  # openreceive_payments rows. See Rate limiting.
  # config.rate_limiting = true
  # config.rate_limiting = { limit_per_hour: 60, limit_per_day: 300 }

  # OR a custom rate-limit hook — receives the same `context` Hash as
  # config.authorize; return false (or raise the engine's rate-limited error)
  # for a 429. Mutually exclusive with config.rate_limiting.
  # config.rate_limit = ->(context) { MyLimiter.allow?(context[:request].ip) }

  # Client-IP extractor for rate limiting and attempt-row stamping. Default:
  # ActionDispatch::Request#ip, which honors Rails' trusted-proxy
  # configuration.
  # config.client_ip = ->(request) { request.headers["CF-Connecting-IP"] }

  # Request-path settlement pass on every engine PAYMENT route (unauthenticated
  # GET /rates never triggers it), ON by default through the durable
  # openreceive_meta gate shared by all Puma workers. Set false when a
  # dedicated worker owns scanning (required with a custom repository).
  # config.opportunistic_reconcile = false
  # config.opportunistic_reconcile = { min_interval_seconds: 10 }

  # Your application otherwise refuses to start on a spend-capable NWC code
  # (also OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true).
  # config.allow_spend_capable_wallet = true

  # Eager production boot preflight, ON by default: the wallet is built and
  # checked at boot so a bad NWC_URI stops the deploy, not the first customer.
  # `rails assets:precompile` is detected and skipped automatically (see
  # Deploying); set false for any other boot that must come up with no wallet
  # secrets. It disables the BOOT check only — the wallet is still checked on
  # the first request.
  # config.eager_preflight = false
end

on_paid runs inside the settlement transaction through the engine’s write-once mark_paid_once!. It runs only for the first settled attempt for a reference. Delivery is at-least-once, so a raise rolls back and the next pass retries. Applications with a custom repository can use the advanced hooks resolve_checkout and on_checkout_created.

OpenReceive::ReconcileJob

OpenReceive::ReconcileJob.perform_later

One reconciliation pass, wrapped for your ActiveJob backend. It runs once.

Where it fits: Enqueue it from your own code when you want a scan soon but not inside the request. For example, after a support agent presses “re-check payment”, or from a scheduler if you run one. It is a convenience around OpenReceive.reconcile!, not something the engine requires.

You do not need to schedule it. By default, settlement is driven by the opportunistic reconcile that runs on requests.

rake openreceive:doctor

bin/rails openreceive:doctor

Step 0 of the agent directions, as one command.

Where it fits: Run it first, before touching the initializer, and again after every deploy or credential change. It tells you which of the three hooks are still placeholders and whether the wallet answers. It never prints a secret, so its output is safe to paste into an issue.

It reports whether each credential (NWC_URI, LSC_URI_*) is PRESENT. Every line is set or unset. No secret value is ever printed, echoed, or partly shown. That is what makes it safe to run in a shared terminal or paste into an issue. It also reports:

• whether OpenReceive.configure ran,
• which of the three hooks are missing or still the generated placeholders (LOGGING_ON_PAID, ALLOW_ALL_AUTHORIZE),
• where the engine is mounted, and
• a best-effort wallet preflight. This is the same eager check a production boot runs, but it reports the result with secrets removed instead of raising.

Outside Rails, the Node CLI’s npx openreceive doctor does the same job.

rake openreceive:reconcile

bin/rails openreceive:reconcile

The same single pass as a rake task. It runs once and prints the number of attempts scanned.

Where it fits: Use it from a cron entry, a console, or a runbook when you want to force a scan now. For example, after a wallet outage, or while finding out why an order is still unpaid. Day to day, the pass that runs on requests does this for you.

rake openreceive:notifications

bin/rails openreceive:notifications

The one documented worker. It is a long-running, opt-in NWC-02 listener built on OpenReceive.listen_for_notifications!, and it retries with backoff. It also reconciles on a timer (OPENRECEIVE_NOTIFICATIONS_RECONCILE_INTERVAL_SECONDS, default 15). That timer is its own safety net for notifications missed while it was down.

Where it fits: Run it as its own long-running process, for example a worker line in your Procfile, when you want orders marked paid the moment the wallet sees the payment. Without it, the app still settles every order, just on the payer’s next status poll.

OpenReceive.reconcile!

OpenReceive.reconcile!(overlap_seconds: 60, now: nil, max_pages: nil, deadline: nil) # => Array<Hash>

Where it fits: Call it from your own job, script, or console when you want one pass now and want the results back in Ruby, for example to show them in an admin view. The rake task and the job above are thin wrappers around it.

Parameters

Returns the check result for each hash in the pass: an array of { "payment_hash", "status", "paid_at"?, "details"? } hashes. It returns [] when the ledger has no pending attempts.

It runs one bounded pass over the ledger the engine owns:

1. Scans the wallet for the oldest OpenReceive::Server::RECONCILE_BATCH_SIZE (200) pending attempts.
2. Delivers settlements through the write-once settlement hook.
3. Saves final state changes.

max_pages: caps the wallet-history pages walked. deadline: is a wall-clock limit the scan checks between page fetches. A pass that runs out of time simply stops walking. A hash the scan never reached stays untouched. Closing an attempt requires a successful scan at or after expiry plus the 900-second grace. The local clock alone never closes it. A wallet failure raises and leaves every row pending.

OpenReceive.maybe_reconcile!

OpenReceive.maybe_reconcile!(now: nil) # => Hash

The gated pass behind the engine’s opportunistic reconcile on requests. The engine runs it as an around_action on its controllers, with exactly one gate claim per request. It is exported for your own routes and middleware, which never run it automatically. Rack applications call it themselves.

Where it fits: Add it to a controller action of your own that a waiting payer polls, such as an order-status endpoint, so settlement gets a chance to run there too. It is safe to call on every request. It returns at once when nothing is pending or another worker just scanned.

It never raises. A failed scan warns and returns scan_failed. The gate stays claimed, so a broken wallet cannot trigger a flood of retries. A page still in flight at the 9 s scan deadline is cut: when earlier pages answered, the pass returns ran and the next pass resumes after them; when none did, the pass fails like any other wallet failure. It returns { "reason" => "ran", "checks" => [...] } (the check hash for each payment hash) or { "reason" => "disabled" | "no_pending" | "gate_busy" | "scan_failed" }.

OpenReceive.listen_for_notifications!

OpenReceive.listen_for_notifications!(overlap_seconds: 60)

Subscribes to the configured NWC client’s payment_received notifications.

Where it fits: You’ll only call this yourself when writing your own worker instead of rake openreceive:notifications, for instance to run it under your own supervisor with your own logging. It blocks, so it belongs in a dedicated process, never in a request or a job with a timeout.

It settles directly the same way the Node listener does. If a payload meets the shared settlement rule and matches a pending attempt, it settles directly through the engine’s mark_paid_once!/on_paid path, with no wallet scan for that invoice. Anything less falls back to one OpenReceive.reconcile! pass. That covers no sign that the payment is final, an unknown hash, or a failed direct settlement. The worker’s periodic pass is the safety net for notifications missed while offline. It raises OpenReceive::ConfigurationError when the client cannot send notifications. Blocking clients do not return until the subscription ends.

The built-in nwc-ruby client is already wired up. openreceive-rails declares it as a runtime dependency, so it is installed with the engine. OpenReceive::NwcRubyReceiveClient forwards subscribe_notifications to that gem’s subscribe_to_notifications. It turns the notification object the gem yields back into the NWC-02 wire payload. So the settlement rule reads state/settled_at exactly as it does on a list_transactions row.

A custom config.nwc_client opts in by supplying subscribe_notifications(&block), which yields those wire payloads (notification_type plus the transaction-shaped notification). The engine filters for payment_received itself, so the client should forward every type the wallet publishes.

Python

The Python engine (pip install openreceive) is the same contract in snake_case:

• the host is a Host dataclass,
• the entry point that knows about storage is an OpenReceiveApp, and
• the FastAPI binding is two functions on top of it.

Django apps use openreceive.django, which has its own quickstart. Flask apps use the recipe. Python APIs and the wire use the same spelling (payment_hash, amount_msats). Money is int msats or decimal strings.

Host (Python)

from openreceive.server import Host
host = Host(amount_for=..., authorize=..., on_paid=..., after_paid=None)

Fields

LOGGING_ON_PAID and ALLOW_ALL_AUTHORIZE are the two named placeholders. The engine warns at boot while either is in use, and openreceive doctor names them.

openreceive_router

from openreceive.fastapi import openreceive_router
app.include_router(openreceive_router(host, engine=engine, rate_limiting=True), prefix="/openreceive")

An APIRouter that serves every route in the OpenAPI contract through the framework-free engine. The endpoint is a sync def run in Starlette’s threadpool. The engine’s own checks are unchanged: 404/405, the JSON-only rule, the Sec-Fetch-Site: cross-site refusal, the declared-fields check, and the 64 KB body cap. The mount prefix is whatever include_router was given.

Parameters

The returned router carries .openreceive, the binding behind it. The CLI’s --app accepts the router, the FastAPI app, or an OpenReceiveApp.

openreceive_lifespan

app = FastAPI(lifespan=openreceive_lifespan(host, engine=engine, lazy=False))

Runs the receive-only wallet preflight when the server starts. Passing the same host + engine= as the router gives the same binding. You can also pass the router itself. On failure it raises ConfigurationError so uvicorn exits. A missing NWC_URI, an unreachable relay, or a spend-capable code stops the deploy. lazy=True delays the check to the first request, which answers 503 WALLET_UNAVAILABLE until the check passes. Startup also sets app.state.openreceive. Shutdown closes the wallet client the binding built.

OpenReceiveApp (Python)

from openreceive.server import OpenReceiveApp, Service
app = OpenReceiveApp(service=service, host=host, repository=repository, prefix="/openreceive", rate_limiting=False, opportunistic_reconcile=True)
status, body, headers = app.handle(HttpRequest(method=..., path=..., headers=..., body=...))
checks = app.reconcile(overlap_seconds=60)      # one bounded pass; the `openreceive reconcile` verb
app.maybe_reconcile()                           # the gated request-path pass: {"reason": "ran" | "disabled" | "no_pending" | "gate_busy" | "scan_failed"}

The framework-free engine, with storage, that the FastAPI router, the Django views and the Flask recipe mount.

• Service(nwc_client, price_provider=…, swap_providers=…, price_currencies=…, env=…) is the wallet, rates and swaps half. Its constructor IS the preflight, and it refuses to start on a bad setup.
• repository is openreceive.storage.sql.SqlPaymentRepository(engine) or the Django ORM repository.
• app.reconciler (settle, handle_notification, attempt_status) is what the notifications worker drives.

payments_schema_sql (Python)

from openreceive.storage.sql import payments_schema_sql, payments_ddl_statements
payments_schema_sql("postgres" | "sqlite" | "mysql", table_name="openreceive_payments", meta_table_name="openreceive_meta") -> str

The official DDL for both tables plus the schema_version seed row, as one script. payments_ddl_statements returns the statements separately, which is what the Alembic revision executes. The FastAPI demo runs it at boot if the table does not exist yet. Production apps apply it once through their own migration workflow.

openreceive scaffold payments (Python)

openreceive scaffold payments --sql --dialect postgres|sqlite|mysql [--table-name …] [--meta-table-name …]
openreceive scaffold payments --alembic --dialect postgres [--out-dir alembic/versions] [--revision <12 hex>] [--down-revision <id>] [--force]

--sql prints the DDL to stdout, with the exactly-once fulfillment note as comments.

--alembic writes <revision>_openreceive_payments.py. The DDL is fixed in op.execute calls, and a downgrade() drops both tables. Set --down-revision to your current head (alembic heads), or edit it in afterwards. A revision with down_revision = None becomes a second base.

It never opens a database connection.

openreceive doctor (Python)

openreceive doctor [--app module:attr] [--offline] [--db <sqlalchemy-url>] [--url http://localhost:8000] [--prefix /openreceive]
openreceive debug-report [...]     # the same lines, always exit 0

It checks:

• the Python version,
• whether NWC_URI is set and can be parsed (never printing the value),
• the LSC_URI_* connections,
• the receive-only relay probe (--offline skips it), and
• whether both tables exist (assert_supported_schema) and which hooks are still placeholders.

For the last check it needs your app. Pass --app with the FastAPI app, the router from openreceive_router, an OpenReceiveApp, or a zero-argument callable that returns one. Without --app, DJANGO_SETTINGS_MODULE selects the Django app.

--db checks the tables at any SQLAlchemy URL instead. --url proves the routes answer under the prefix, by getting the engine’s own JSON 404 on an unknown path. The exit code is 1 if any line fails. Every failing line states its fix.

openreceive reconcile / openreceive notifications

openreceive reconcile --app main:app [--overlap-seconds 60]
openreceive notifications --app main:app [--interval-seconds 15]

reconcile runs one bounded pass over the pending attempts and prints how many ended in each status. It matches rake openreceive:reconcile. Use it in a runbook or from cron. The pass that runs on requests covers day-to-day settlement.

notifications is the one documented worker. It is a long-lived NWC-02 payment_received listener that retries with backoff. It also runs the periodic pass (OPENRECEIVE_NOTIFICATIONS_RECONCILE_INTERVAL_SECONDS, default 15) as the safety net for notifications missed while it was down. Run one, as its own process. Without it, every order still settles on the payer’s next poll.

In Django, the commands are manage.py openreceive_reconcile / openreceive_notifications.

PHP

The Composer package openreceive/openreceive (namespace OpenReceive\) is for a plain-PHP app. The Laravel adapter (openreceive/laravel) wraps the same classes. It requires PHP ≥ 8.2, 64-bit, and ext-gmp. Public arrays use the wire’s snake_case keys. Methods are camelCase. Money is integer msats or decimal strings, never a float. The package’s own static analysis forbids floats in the money path.

OpenReceive\Host

interface Host {
    public function authorize(AuthorizeContext $context): bool;
    public function amountFor(string $reference): ?array;   // ['currency' => 'USD', 'value' => '12.00', 'description' => ?] or ['sats' => 1200]; null = 404
    public function onPaid(PaymentSettlement $settlement): void;
}

The host contract: one object with three methods. It is the only bridge between the engine and your data. Where it fits: it is the first thing Engine takes, and it is the whole quickstart.

• authorize runs on every mounted route.
• amountFor runs only where a price is minted or quoted. Payer input never carries an amount.
• onPaid runs inside the settlement transaction, for the first settled attempt of a reference.

Also implement OpenReceive\Hosts\AfterPaid when something must run after COMMIT, such as an email or a webhook. It is best-effort and never retried.

Two placeholder traits exist for scaffolding: Hosts\AllowAllAuthorize (allows everything) and Hosts\LoggingOnPaid (logs and fulfills nothing). Engine warns through its logger at construction while a host uses either, and Doctor names them. Replace both before anything real.

Fields of PaymentSettlement (readonly):

• reference
• paymentHash
• paidAt (Unix seconds)
• details: the transaction snapshot the wallet observed, observed_at, and paid_at_source, or null
• connection: the DatabaseConnection of the settlement transaction (execute() / query() with positional ? placeholders). It is null in afterPaid.

The authorize context (PHP)

OpenReceive\Server\AuthorizeContext is readonly. It has:

• action: checkout.prepare, checkout.create, payment.check, swap.quote, swap.create, swap.read, or swap.refund.
• request: the PSR-7 ServerRequestInterface on the plain mount. Laravel passes its own request object.
• resource: ['reference' => …, 'payment_hash' => ?], copied from the payer’s JSON body before any lookup. It is a claim, not proof.
• helpers reference() and paymentHash(). paymentHash() is null except on payment.check, swap.read, and swap.refund.

A custom rateLimit hook receives the same object.

OpenReceive\Server\Service

$service = Service::fromEnvironment();   // NWC_URI, LSC_URI_PRIMARY/BACKUP, OPENRECEIVE_* from getenv() + $_ENV
$service = new Service($nwcClient, $priceProvider, $swapProviders, ['USD'], $clock, $allowSpendCapableWallet, $env, $logger, $http);

The checkout service, which works with any storage. It covers prepare and create, the bounded wallet reconcile pass, swap quote/create/get/refund, rates, and the receive-only preflight at boot.

The preflight runs in the constructor. It fails closed, refusing to start, when:

• NWC_URI is missing or invalid,
• the wallet lacks make_invoice or list_transactions,
• there is no shared encryption mode, or
• the wallet advertises a spend method. OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true or $allowSpendCapableWallet relaxes only this last check.

fromEnvironment(?array $env, array $priceCurrencies, PriceProvider|false|null $priceProvider, ?array $swapProviders, bool $allowSpendCapableWallet, ?LoggerInterface $logger, ?HttpTransport $http):

• Pass $env explicitly when the framework caches configuration.
• Pass false for no rates.
• Pass [] for no swaps.

The direct API is prepareCheckout(), createCheckout(), reconcilePayments(), quoteSwap(), createSwap(), getSwap(), refundSwap(), listRates(), listSwapOptions() and subscribeNotifications(). It takes and returns snake_case arrays. Errors are OpenReceive\Server\Errors\*, extending HttpError (status, errorCode, retryable, details, retryAfterSeconds).

OpenReceive\Server\Engine

$engine = new Engine(
    $host, $repository, $service,
    opportunisticReconcile: true,          // false when a worker owns scanning; ['min_interval_seconds' => n]
    rateLimiting: false,                   // true = 60/hour per IP; ['limit_per_hour' => , 'limit_per_day' => ]
    rateLimit: null,                       // custom fn (AuthorizeContext): bool — exclusive with rateLimiting
    clientIp: null,                        // fn (mixed $request): ?string; default REMOTE_ADDR of the PSR-7 request
    logger: null,                          // any PSR-3 logger
    prefix: '/openreceive',
    responseFactory: null,                 // a PSR-17 ResponseFactoryInterface; nyholm/psr7 is auto-discovered
);

The quickstart’s way of putting the parts together. It matches Rails’ Configuration. It takes a Host, a PaymentRepository and a Service, and from them gives you:

• the request handler,
• the PSR-15 mount, with opportunistic reconcile on requests,
• the settlement hook,
• the reconciler,
• the notifications worker, and
• the doctor.

In plain PHP, build one per request, since each request is its own process. Under a framework, bind one in the container.

Behind a reverse proxy, pass clientIp: fn ($request) => $request->getHeaderLine('x-forwarded-for') (or your framework’s trusted-proxy answer). That way the per-IP cap counts the payer.

Engine notificationsWorker

$engine->notificationsWorker()->run();   // blocks; ->stop() ends it

The one documented worker. It is a long-lived NWC-02 payment_received listener that retries with backoff. It also runs a periodic reconcile pass as its own safety net. PHP has no threads, so the periodic pass runs when the blocking subscription is idle, once a second. Run it as its own process. Without it, every order still settles on the payer’s next poll.

A payment_received payload that meets the settlement rule settles the matching pending attempt directly. Anything less falls back to one bounded reconcile pass.

OpenReceive\Storage

$db = new PdoConnection($pdo);                       // dialect from PDO::ATTR_DRIVER_NAME: pgsql | mysql | sqlite
$repository = new SqlPaymentRepository($db);         // (?callable $clock, string $table, string $metaTable)
PaymentsSchema::statements($dialect);                // list<string> DDL: openreceive_payments + openreceive_meta
PaymentsSchema::dropStatements();                    // the down()
PaymentsSchema::migrate($db);                        // both, in one call

PdoConnection wraps the PDO your app already opens. It sets ERRMODE_EXCEPTION, and sets the SQLite busy timeout through PDO::ATTR_TIMEOUT.

An app with no PDO implements DatabaseConnection instead, as the WordPress plugin does. It has dialect(), query(), execute(), transaction(), lastInsertId(), and positional ? placeholders.

SqlPaymentRepository is responsible for the per-reference commit lock in each dialect, write-once settlement, the reconciliation transitions, and the openreceive_meta compare-and-swap (CAS) gate. It never selects swap_data into a public array.

As an escape hatch, you can implement PaymentRepository yourself. Then set opportunisticReconcile: false, unless you also implement claimReconcileGate and checkpointReconcileGate.

OpenReceive\Server\Doctor

Doctor::report(array $env, ?Host $host, ?callable $walletCheck, ?string $mountedAt): array   // list<string>
Doctor::placeholderWarnings(Host $host): array

Step 0 of the agent directions, as report lines. It reports:

• each credential as set or unset, never its value,
• the host class, and whether authorize/onPaid are still the placeholder traits,
• where the handler is mounted, and
• the wallet preflight. $walletCheck is a closure that builds the Service. If it throws, the error is reported, never raised.

$engine->doctor() does the same for a built engine. The output is safe to paste into an issue.

OpenReceive\Testing

FakeWallet (a ReceiveNwcClient) and FakeSwapProvider (a SwapProvider), built on the testkit contract, plus Rates\StaticPriceProvider. See Testing your integration.