openreceive-server 0.4.10 → 0.4.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c474debc4035b3cb2f6a5b4f3b7e4ee3088c99abfead02e92e23a37d4a26b5db
-  data.tar.gz: ba690e555070b4349fff546f99b2fc737f2787607593c6577fb7ef3bdc849007
+  metadata.gz: 39aa74c7725e2887e61131f418feceb4a03194b5a079ac46307f685600d062f5
+  data.tar.gz: 33e89f647cef3990e85ce10990ec868267251001bbf03b280921d522bdd5dce6
 SHA512:
-  metadata.gz: cf6536250d18edf1a741d32cdb30aac45a309b1663c9ae2e219df5897987e7d53f0f6dc522a6309bd73faec98f65bdbb45f4882779ad5e9a1b369da04b04e0c0
-  data.tar.gz: 4526bd34483b0b3d9480cf25d13c291cecc0a7d3bae9155be76fa677e07a17ed99c8d5d0eb27bc3fac010fdf12c9b09c23492cffdc0e0c17f5b1ddc3f37635ed
+  metadata.gz: 928f356068c9f63b15b9955ea89fc6e77187828eb41a619c4a9bce4fbdd8b2b61c73e432387a777f35005e32a093347531b41e065e28e5b3b48551d813d1946d
+  data.tar.gz: fd128c515bd6a1f99c836dae1c57c3fd3d3468a52130d2e5b7ffacc5ba049d3ed84ac1b5e34b4c626fe9f00c91469030bb68f3343debf4f6aff658337fa38ca3

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.11 - 2026-09-21
+
+The mounted HTTP routes mint invoices with the host's own description. The
+display string `amount_for` returns beside the price is now the default
+`make_invoice` memo, so a host that writes no invoice code stops minting
+BOLT11s with an empty description. An explicit request-body `memo` still wins
+and still carries the length cap; a host that returns no description still
+mints without one.
+
+Payment safety and disclosure fixes: a checkout's `created_at_source` (whether
+the creation time came from the wallet or from us) is internal and is stripped
+from every public body, error responses carry a redacted message and no
+arbitrary internal `details`, unexpected errors are reported to `Rails.error`
+detached from their cause and backtrace, a host callback that returns an
+invalid amount raises `InternalHostError` instead of leaking a validation
+failure, and a refund address is rejected unless the attempt has a saved,
+supported pay-in asset. A host that refuses an attempt now answers 409 with
+instructions withheld, while genuine storage failure stays a retryable 503.
+
 ## 0.4.10 - 2026-09-16
 
 Release in lockstep with the 0.4.10 stablecoin checkout fix. The swap fee

data/lib/openreceive/server/errors.rb

@@ -97,7 +97,7 @@ module OpenReceive
     class HostPersistenceError < StandardError
       attr_reader :status, :code, :retryable
 
-      def initialize(message = "The host could not persist this payment attempt; " \
+      def initialize(message = "Payment storage is unavailable; " \
                                "payer instructions were withheld. Please retry.")
         super(message)
         @status = 503

data/lib/openreceive/server/request_handler.rb

@@ -88,7 +88,7 @@ module OpenReceive
                      else
                        @service.create_checkout(
                          "reference" => reference, "amount" => required_amount(resolved),
-                         "memo" => validated_memo(body), "metadata" => body["metadata"]
+                         "memo" => mint_memo(body, resolved), "metadata" => body["metadata"]
                        )
                      end
           commit(checkout, nil, request) unless resolved["payment_hash"]
@@ -99,7 +99,7 @@ module OpenReceive
           # committed invoice amount — and served on the re-fetch path too, so
           # a repeated create answers with the same shape it first did.
           payment_methods = @service.list_swap_options(amount_msats: checkout["amount_msats"])
-          body = { "checkout" => checkout, "payment_methods" => payment_methods }
+          body = { "checkout" => public_checkout(checkout), "payment_methods" => payment_methods }
           description = resolved_description(resolved)
           body["description"] = description if description
           success(201, body, request_id)
@@ -180,7 +180,7 @@ module OpenReceive
                      "reference" => reference,
                      "amount" => required_amount(resolved),
                      "pay_in_asset" => asset,
-                     "memo" => validated_memo(body),
+                     "memo" => mint_memo(body, resolved),
                      "metadata" => body["metadata"]
                    )
                  end
@@ -255,9 +255,9 @@ module OpenReceive
           retryable = Nwc::RETRYABLE_ERROR_CODES.include?(code) if retryable.nil?
           status = retryable ? 503 : 502
         end
-        body = { "code" => code, "message" => error.message, "request_id" => request_id }
+        body = { "code" => code, "message" => Nwc.redact_error_text(error.message), "request_id" => request_id }
         body["retryable"] = retryable unless retryable.nil?
-        body["details"] = error.details if error.respond_to?(:details) && error.details.is_a?(Hash)
+        # Arbitrary internal details and causes have no public projection.
         response_headers = headers(request_id)
         # Mirrors the JS handler: a Retry-After hint (whole seconds, minimum 1)
         # rides along with retryable throttling errors.
@@ -271,6 +271,10 @@ module OpenReceive
 
       private
 
+      def public_checkout(checkout)
+        checkout.reject { |key, _| key.to_s == "created_at_source" }
+      end
+
       # Status refresh with no request-level pass: one-attempt reconcile_payments,
       # delivering settlement inline. A truncated walk raises WalletUnavailableError
       # (retryable 503) rather than reporting not_found.
@@ -391,11 +395,11 @@ module OpenReceive
         # (database down, bug): retryable 503, never a payer-blaming conflict
         # — mirrors the JS handler's commit().
         raise e if e.respond_to?(:status) && e.respond_to?(:code)
-        raise HostPersistenceError
+        raise ConflictError, "The host did not accept this payment attempt; payer instructions were withheld."
       end
 
       def public_swap(swap)
-        swap.reject { |key, _| key == "swap_data" }
+        swap.reject { |key, _| key == "swap_data" }.merge("checkout" => public_checkout(swap.fetch("checkout")))
       end
 
       # Payer-facing subset of a settlement's wallet details, whitelisted
@@ -442,7 +446,9 @@ module OpenReceive
       # preimages.
       def report_unexpected_error(error, request_id)
         if defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
-          ::Rails.error.report(error, handled: true, source: "openreceive")
+          # Detached diagnostic: no cause, stack or attached provider configuration.
+          safe_error = RuntimeError.new(OpenReceive::Nwc.redact_error_text(error.message))
+          ::Rails.error.report(safe_error, handled: true, source: "openreceive")
         else
           origin = Array(error.backtrace).first
           line = "[openreceive] unexpected #{error.class} (request_id=#{request_id})" \
@@ -550,10 +556,24 @@ module OpenReceive
         memo
       end
 
+      # The description that goes INTO the invoice. An explicit body memo wins,
+      # so a client that writes its own copy keeps it; otherwise the host's
+      # display string is it. Without the fallback a host on the mounted routes
+      # mints BOLT11s with no description at all and the payer's wallet shows a
+      # blank line next to the amount. Only the body memo carries the length
+      # cap: the cap bounds client input, and the host description is host data
+      # exactly like the price beside it.
+      def mint_memo(body, resolved)
+        memo = validated_memo(body)
+        blank = memo.nil? || (memo.is_a?(String) && memo.strip.empty?)
+        blank ? resolved_description(resolved) : memo
+      end
+
       # What the payer is buying, in the host's own words: one optional display
-      # string the host returns beside the price. Response only — it is never
-      # read from a request body, because the payer does not get to write the
-      # copy next to the amount. Blank is the same as absent.
+      # string the host returns beside the price. Never read from a request
+      # body, because the payer does not get to write the copy next to the
+      # amount; it rides the prepare and create responses and, via mint_memo,
+      # defaults the invoice description. Blank is the same as absent.
       def resolved_description(resolved)
         value = resolved["description"]
         return nil unless value.is_a?(String)

data/lib/openreceive/server/service.rb

@@ -162,6 +162,7 @@ module OpenReceive
             "bolt11" => wallet.fetch("invoice"),
             "amount_msats" => wallet.fetch("amount_msats"),
             "created_at" => created_at,
+            "created_at_source" => wallet["created_at"].nil? ? "host" : "wallet",
             "expires_at" => expires_at,
             "fiat_quote" => fiat_quote
           }
@@ -563,6 +564,12 @@ module OpenReceive
       end
 
       def resolve_amount(input)
+        resolve_amount_value(input)
+      rescue ArgumentError, TypeError, KeyError, ValidationError
+        raise InternalHostError, "The host supplied an invalid payment amount."
+      end
+
+      def resolve_amount_value(input)
         amount = stringify(input)
         if amount.key?("sats")
           return [OpenReceive::Money.direct_to_msats(currency: "SATS", value: amount.fetch("sats")), nil]
@@ -639,6 +646,9 @@ module OpenReceive
       # checksum — a false accept here sends the payer's money somewhere
       # unrecoverable. Mirrors the JS normalizeRefundAddress exactly.
       def normalize_refund_address(value, pay_in_asset)
+        unless OpenReceive::Server::Swap::Assets::PAY_IN_ASSETS.include?(pay_in_asset)
+          raise InternalHostError, "Swap recovery requires a supported pay-in asset/network."
+        end
         normalized = value.to_s.strip
         if normalized.empty? || normalized.length > 300
           raise ValidationError, "refundAddress is invalid."

data/lib/openreceive/server/swap/fixedfloat.rb

@@ -306,9 +306,7 @@ module OpenReceive
         def post(path, body)
           @weight_budget&.reserve(path)
           body_string = JSON.generate(body)
-          # Surface every outbound request before the call. The host sink is
-          # responsible for sanitizing nested secrets; the API key and HMAC
-          # signature live in headers and are deliberately never logged.
+          # Host diagnostic sinks receive summaries only, before any provider I/O.
           log_api_request(path, body)
           begin
             response = @http.call(
@@ -341,9 +339,7 @@ module OpenReceive
               message: "FixedFloat #{path} returned invalid JSON."
             )
           end
-          # Surface every response (including API-error envelopes) before any
-          # raise. The host sink sanitizes nested secrets — notably the order
-          # token in a create/order response — so this must not pre-redact.
+          # Summarize before invoking any host sink, including error envelopes.
           log_api_response(path: path, status: status, ok: ok,
                            code: parsed["code"], msg: parsed["msg"], data: parsed["data"])
           unless ok
@@ -369,7 +365,10 @@ module OpenReceive
         end
 
         def log_api_request(path, body = {})
-          @api_request_logger&.call("provider" => @name, "path" => path, "body" => body)
+          @api_request_logger&.call(
+            "provider" => @name, "path" => path, "has_body" => !body.empty?,
+            "has_token" => body.is_a?(Hash) && !body["token"].nil?
+          )
         rescue StandardError
           nil
         end
@@ -377,7 +376,7 @@ module OpenReceive
         def log_api_response(path:, status:, ok:, code: nil, msg: nil, data: nil)
           @api_response_logger&.call(
             "provider" => @name, "path" => path, "status" => status, "ok" => ok,
-            "code" => code, "msg" => msg, "data" => data
+            "code" => code.is_a?(Numeric) ? code : nil, "has_data" => !data.nil?
           )
         rescue StandardError
           nil

data/lib/openreceive/server/version.rb

@@ -2,6 +2,6 @@
 
 module OpenReceive
   module Server
-    VERSION = "0.4.10"
+    VERSION = "0.4.11"
   end
 end

data/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
@@ -119,6 +119,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the plugin itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -157,9 +159,9 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 In BTCPay, open **Server Settings → Plugins**, search the plugin directory
 for **OpenReceive**, click **Install**, and restart BTCPay when prompted.
-BTCPay creates the plugin's one table (`openreceive_swaps`, schema
-`BTCPayServer.Plugins.OpenReceive`) in its own Postgres at startup; nothing
-else is created.
+BTCPay creates the plugin's two tables (`openreceive_invoices` and
+`openreceive_swaps`, schema `BTCPayServer.Plugins.OpenReceive`) in its own
+Postgres at startup; nothing else is created.
 
 To build the plugin from source instead, follow
 [the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).

data/skills/integrate-openreceive/references/django.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI
@@ -130,7 +130,7 @@ itself, and they hold for every integration.
   a placeholder that allows everything (`manage.py check` warns
   `openreceive.W002` while it is set) — replace it with this app's real
   ownership check, same as `on_paid`.
-- `on_paid` must be idempotent. It runs once per `reference` — your order
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -307,6 +307,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -480,7 +482,7 @@ The host class needs three things: authorization, the trusted price, and
 fulfillment. All three receive the `reference` — a string you choose, and the
 fulfillment identity: your order id, one per thing you fulfill, created before
 checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
+it, but `on_paid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

data/skills/integrate-openreceive/references/fastapi.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -116,7 +116,7 @@ itself, and they hold for every integration.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read the Starlette request's session, cookie or
   auth dependency; never trust a body field.
-- `on_paid` must be idempotent. It runs once per `reference` — your order id, one
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -301,6 +301,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -475,7 +477,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `on_paid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -524,7 +526,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A page without a bundler renders the same checkout as a custom element:
 `<openreceive-checkout reference="…" prefix="/openreceive">` from

data/skills/integrate-openreceive/references/fastify.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and
@@ -107,7 +107,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -284,6 +284,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -477,7 +479,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -526,7 +528,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

data/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -121,7 +121,7 @@ itself, and they hold for every integration.
   scaffolds `use AllowAllAuthorize;`, a placeholder trait that allows
   everything (the engine warns at boot while it is there) — replace it with
   this app's real ownership check, same as `onPaid`.
-- `onPaid` must be idempotent. It runs once per `reference` — your order
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -291,6 +291,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -456,7 +458,7 @@ variable as set/unset only.
 price, and fulfillment. All three receive the `reference` — a string you
 choose, and the fulfillment identity: your order id, one per thing you
 fulfill, created before checkout, kept across retries, never reused.
-OpenReceive never looks inside it, but `onPaid` runs once per reference, a new
+OpenReceive never looks inside it, but `onPaid` commits fulfillment once per reference, a new
 checkout under a reference that already settled is refused with 409, and a
 fresh id per page load lets one order be paid twice.
 

data/skills/integrate-openreceive/references/next.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Next.js App Router application — the app you are already
 working in. You do not need a copy of the OpenReceive source: the packages are
@@ -109,7 +109,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -290,6 +290,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -496,7 +498,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -576,7 +578,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

data/skills/integrate-openreceive/references/node.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the
@@ -104,7 +104,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -276,6 +276,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -454,7 +456,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -503,7 +505,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

data/skills/integrate-openreceive/references/php.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist
@@ -125,7 +125,7 @@ itself, and they hold for every integration.
   is a placeholder that allows everything (the engine warns at boot while a
   host uses it) — replace it with this app's real ownership check, same as
   `onPaid`'s `Hosts\LoggingOnPaid`.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -301,6 +301,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -512,7 +514,7 @@ prices with exact decimal math, and returns the order id the page will pass as
 the `reference`. OpenReceive never prices from payer input. The `reference` is
 a string you choose, and it is the fulfillment identity: your order id — one
 per thing you fulfill, created before checkout, kept across retries, never
-reused. `onPaid` runs once per reference, a new checkout under a reference
+reused. `onPaid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

data/skills/integrate-openreceive/references/rails.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 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
@@ -116,7 +116,7 @@ itself, and they hold for every integration.
   body field. The generator installs `OpenReceive::ALLOW_ALL_AUTHORIZE`, a
   placeholder that allows everything (the engine warns at boot while it is
   set) — replace it with this app's real ownership check, same as `on_paid`.
-- `config.on_paid` must be idempotent. It runs once per `reference` — your order
+- `config.on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -285,6 +285,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -432,7 +434,7 @@ The initializer needs three things: authorization, the trusted price, and
 fulfillment. All three receive the `reference` — a string you choose, and the
 fulfillment identity: your order id, one per thing you fulfill, created before
 checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
+it, but `on_paid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

data/skills/integrate-openreceive/references/woocommerce.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Install and configure the OpenReceive gateway in the existing WooCommerce
 store. Preserve its theme, checkout, customer accounts, order model and prices.
@@ -73,6 +73,8 @@ flows; a receive-only NWC wallet cannot send payments.
 - [Agent Directions: BTCPay Server](https://openreceive.org/guides/agent-directions-btcpay.md)
 - [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive-server
 version: !ruby/object:Gem::Version
-  version: 0.4.10
+  version: 0.4.11
 platform: ruby
 authors:
 - OpenReceive
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.10
+        version: 0.4.11
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.10
+        version: 0.4.11
 description: |
   Accept Bitcoin Lightning payments directly into a wallet you control, from your
   Ruby or Rack application. OpenReceive provides invoice creation, payment checks,