spree-bank_payments 5.2.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7bb0454adf07aad2127a114af121975941265c60b04ba329aa870d5bed31243
-  data.tar.gz: 887a05355e75ae225476c219f4b355dae87354c0e026e5f92bbe1bf56a46bf14
+  metadata.gz: 6a51b19c1448a4d27b386e8e65276fb900e18528f4e7bfd4f539e33b559414fa
+  data.tar.gz: 51ed0b549ce5d0bf543118430c45cd49cb6c5a66646a031ef94980c6d6c6035c
 SHA512:
-  metadata.gz: d44fd3f4f89ad61d1a75e8393c0cb7f62a104ad4a710584e4c789b189a9a66d6154f23e6a49d3d075c16c7acf81740e18c9a40b86b4a9a046d6176b6c0266639
-  data.tar.gz: 96092e1b5ff5e6fd9cbd5d92a604ae0624ba506a6b0e8f76d9a9465ac819d8e9748c4754481f59160d622716821f795d07fbcd60f0b09530adcb47f3139e8da8
+  metadata.gz: 228b83f83281f96655f08ff8e9f0258f4a7031ac3c618643e5d962ecc5d999d9a4e4d4a0d1e4d952fca49d3e26649eaa766269d92a40551e806e3169aa0505f1
+  data.tar.gz: 7c295fe395cd41e19d60fadefa0da4467d4873b12cd4658e7c13d4b1fb595b729d93490182fe6f23d85f8ef7104c87e097e30b441b6c5a9cdeb3d77c004fc16a

data/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.3.0
+
+### Upgrading from 5.2.0
+
+Adds columns, so this is not gem-bump-only:
+
+```sh
+bin/rails spree_bank_payments:install:migrations
+bin/rails db:migrate
+```
+
+**Run the migration before or with the deploy, never after.** `Gateway#health`
+reads `reconciler_state.health_status`, and it is now on the checkout path.
+In a rolling deploy, any pod running 5.3.0 against the 5.2.0 schema raises
+`NoMethodError` on `health_status` for every non-Manual gateway — a checkout
+500 for the whole window between the code going out and the migration landing.
+The columns are additive and nullable, so 5.2.0 pods are perfectly happy
+against the 5.3.0 schema; migrate first and the window does not exist.
+
+**A revoked consent means unpaid orders stop expiring.** `ExpireSessionsJob`
+gates on `reconciler_healthy?` and refuses to cancel while it cannot see the
+bank, which is correct — cancelling orders customers have already paid for is
+the worse failure. But `:consent_revoked` is by definition a state that never
+resolves on its own, so from the moment it is reported, unpaid orders and the
+stock they reserve accumulate until a human re-authorises the provider. Alert
+on `reason="consent_revoked"` and treat it as a page, not a ticket.
+
+### Added
+
+**Three-state reconciler health.** `Reconcilers::Base#health` returns `:ok`,
+`:transient` or `:consent_revoked`. A boolean could not separate a retryable
+provider outage from a dead authorisation, and the two need different responses:
+`:transient` keeps offering at checkout, because those transfers still arrive
+and reconcile once the provider returns, while `:consent_revoked` withdraws the
+payment method, because nothing will ever reconcile against it.
+
+**Backward compatible.** A reconciler written against 5.1.1 or 5.2.0, overriding
+only `#healthy?`, works unmodified — `#health` derives from it. A reconciler
+overriding only `#health` gets `#healthy?` derived in turn.
+
+**Health transition logging, owned by core.** Logged on transition and at most
+hourly thereafter, with a stable `event=` key so alert rules never depend on
+prose. `:transient` logs WARN, `:consent_revoked` logs ERROR, recovery logs INFO.
+`bank_transfer.reconciler_health.unhealthy` and
+`bank_transfer.reconciler_health.recovered` are also published through
+`Spree::Events`. They sit under the same `bank_transfer.` prefix as every other
+event this gem publishes, so `Spree::Events.subscribe('bank_transfer.*', …)` —
+the pattern the README documents — receives them.
+
+Note these are distinct from the flat `bank_transfer.reconciler_unhealthy`
+published by `ExpireSessionsJob`, which is unchanged: that one says the expiry
+job declined to cancel anything, this pair reports the reconciler's own health.
+
+The `reason` is drawn from a closed enum — `ok`, `provider_error`,
+`consent_revoked`, `unknown` — and unrecognised values collapse to `unknown`.
+It is never built from an exception message or a response body. The enum is
+deliberately only what core can actually emit: widening it later is
+non-breaking, narrowing it is not.
+
+**`pooled` on bank accounts.** Carried from `AccountData` through `SyncAccounts`.
+A pooled account shares its coordinates with other customers of the provider, so
+the payment reference is the only thing separating two payers. Auto-apply has
+always required an exact reference match; `spec/services/spree/bank_payments/pooled_account_matching_spec.rb`
+now locks that invariant explicitly.
+
 ## 5.2.0
 
 ### Upgrading from 5.1.1

data/README.md

@@ -99,6 +99,18 @@ every order regardless of currency.
   `sync_accounts` raises, times out, or returns an empty array while
   accounts already exist, the whole sync aborts with no writes — an auth
   failure must never be read as "every account disappeared."
+- **`pooled` marks an account whose coordinates are shared.** Some providers
+  hand every customer the same IBAN and separate the payers by reference
+  alone. A provider reports this through `AccountData#pooled` (default
+  `false`, so a provider that never sets it behaves exactly as before) and
+  it is shown as a **Pooled** badge on the bank accounts screen. It changes
+  nothing about auto-apply — that has always required an exact normalized
+  reference match, on every account — but it changes how a human must read
+  the unmatched queue. Suggestions there are ranked partly on fuzzy
+  payer-name similarity, and on a pooled account a plausible name is not
+  evidence of who paid: two unrelated customers arrive on identical
+  coordinates. The queue therefore warns when a transfer landed on a pooled
+  account, and the reference is the thing to verify before applying.
 
 ### Writing a provider's `sync_accounts`
 
@@ -221,6 +233,15 @@ of installing this gem, not as an afterthought.
 
 ## The health gate
 
+There are two health mechanisms in this gem and they decide different things.
+This one — `reconciler_healthy?` — gates **expiry**: whether
+`ExpireSessionsJob` is allowed to cancel anything. The other, described under
+[`#health`](#health), gates **checkout**: whether bank transfer is offered at
+all. Checkout availability is decided by `#health` and only by `#health`; a
+stale poll never removes the payment method from the storefront, and a
+reconciler can be perfectly healthy here while `#health` reports
+`:consent_revoked`, or the reverse.
+
 `ExpireSessionsJob` refuses to cancel orders when the reconciler has not
 polled successfully within three poll intervals (`poll_interval_minutes`).
 This matters because expiry and reconciliation are decoupled: if a bank
@@ -255,9 +276,16 @@ The gem never sends notifications directly — it publishes to
 | `bank_transfer.reminder_due` | An unpaid session is approaching its expiry deadline |
 | `bank_transfer.expired` | `ExpireSessionsJob` cancels an unpaid order |
 | `bank_transfer.session_superseded` | An open session is closed because its order was already paid another way — the order is left alone |
-| `bank_transfer.reconciler_unhealthy` | The health gate trips (see above) |
+| `bank_transfer.reconciler_unhealthy` | The [health gate](#the-health-gate) trips — `ExpireSessionsJob` declined to cancel anything because the reconciler is stale |
+| `bank_transfer.reconciler_health.unhealthy` | `PollJob` reports a *transition* into `:transient` or `:consent_revoked` — and at most hourly while it persists. Carries `status`, `reason` and `consecutive_failures` (see [`#health`](#health)) |
+| `bank_transfer.reconciler_health.recovered` | The same reporter sees health return to `:ok` |
 | `bank_transfer.expiry_failed` | `ExpireSessionsJob` hits an error cancelling a specific session |
 
+The two `reconciler` events are not the same signal:
+`reconciler_unhealthy` says the expiry job stood down, while the
+`reconciler_health.*` pair reports the reconciler's own state and is what
+decides whether checkout offers bank transfer at all.
+
 Payloads contain serializable primitives only — never AR objects — because
 subscribers may run async via ActiveJob. See
 `Spree::PaymentSessions::BankTransfer#notification_payload` for the exact
@@ -316,13 +344,72 @@ contract methods:
 
 - `#poll(since:)` — returns an `Array<Spree::BankPayments::TransferData>`
 - `#parse_webhook(raw_body, headers)` — returns `TransferData` or `nil`
-- `#healthy?` — boolean; feeds the health gate above
+- `#health` or `#healthy?` — see below; `#health` decides checkout
+  availability, `#healthy?` feeds the [health gate](#the-health-gate) that
+  decides expiry
 - `#configured?` — boolean; whether credentials/settings are complete
 
 `Base` also provides `#sync_accounts`, returning `[]` by default — override
 it if your provider can enumerate accounts, returning an
 `Array<Spree::BankPayments::AccountData>`.
 
+### `#health`
+
+Override either `#health` or `#healthy?` — never both, and never neither.
+Each derives from the other, so a reconciler written before 5.3.0 that only
+implements `#healthy?` keeps working unmodified, and a reconciler that only
+implements `#health` gets `#healthy?` derived from it. Overriding neither
+raises `NotImplementedError` rather than recursing.
+
+`#health` returns one of three symbols. A boolean cannot separate a retryable
+provider outage from a dead authorisation, and checkout has to treat them
+differently:
+
+| State | Meaning | Withdraws from checkout? |
+|---|---|---|
+| `:ok` | Reconciling normally | No |
+| `:transient` | A provider outage or similar — expected to recover on its own | No — those transfers still arrive and reconcile once the provider returns |
+| `:consent_revoked` | The authorisation is dead; nothing will ever reconcile against it | Yes |
+
+**This is the gate that decides whether checkout offers bank transfer**, and
+the only one. The [health gate](#the-health-gate) above is a separate
+mechanism reading a separate signal (`reconciler_healthy?`, driven by poll
+staleness) and it only ever decides whether `ExpireSessionsJob` may cancel —
+it never changes what a customer is shown.
+
+`Gateway#health` is the persisted view `available_for_order?` reads on every
+checkout render — it never calls the reconciler directly, so a provider's live
+check never lands on the storefront's critical path. `PollJob` is what
+refreshes it, reporting health after every poll through `HealthReporter`,
+which logs the transition and then at most hourly while the condition
+persists (WARN for `:transient`, ERROR for `:consent_revoked`, INFO on
+recovery) and publishes `bank_transfer.reconciler_health.unhealthy` /
+`.recovered` through `Spree::Events`.
+
+Query the unhealthy log line with LogQL:
+
+```logql
+{namespace=~"your-ns-.*"} |= "bank_transfer.reconciler_health.unhealthy" | logfmt
+```
+
+`reason=` is drawn from a closed enum, never from an exception message or a
+response body — that is how a bearer token reaches a log aggregator. The whole
+vocabulary is four values:
+
+| `reason` | Emitted when |
+|---|---|
+| `ok` | The poll succeeded — carried on the recovery line |
+| `consent_revoked` | The reconciler reported `:consent_revoked` after a failed poll |
+| `provider_error` | Any other poll failure |
+| `unknown` | A reason outside this enum was passed in and was discarded |
+
+`reason="consent_revoked"` warrants an immediate page — nothing will
+reconcile until a human re-authorises it, and unpaid orders will not expire
+while the gem is blind (see [The health gate](#the-health-gate)). Any other
+reason should only alert after roughly thirty minutes sustained, since a brief
+provider blip recovers on its own and paging on every transient hiccup trains
+people to ignore the alert.
+
 Register it:
 
 ```ruby

data/app/controllers/spree/admin/bank_transfers_controller.rb

@@ -14,8 +14,14 @@ module Spree
       before_action :load_recordable_payment_methods, only: %i[new create]
 
       def index
+        # includes(:bank_account) because the view asks every row whether its
+        # account is pooled. The association is declared `-> { with_deleted }`,
+        # which preloads fine, and it must stay that way: a soft-deleted
+        # account would otherwise resolve to nil and silently drop the pooled
+        # warning on exactly the rows still quoting its coordinates.
         @pagy, @transfers = pagy(
-          Spree::BankPayments::IncomingTransfer.unmatched.order(occurred_at: :desc)
+          Spree::BankPayments::IncomingTransfer.unmatched.
+            includes(:bank_account).order(occurred_at: :desc)
         )
 
         @suggestions = @transfers.each_with_object({}) do |transfer, acc|

data/app/jobs/spree/bank_payments/poll_job.rb

@@ -25,6 +25,7 @@ module Spree
         end
 
         state.record_success!
+        report_health(payment_method, :ok, :ok)
       rescue StandardError => e
         # Never re-raise: one misconfigured payment method must not stop the
         # others, and the recorded failure is what flips the health gate.
@@ -33,6 +34,64 @@ module Spree
         # here can't escape and wedge every payment method after this one.
         state&.record_failure!(e.message)
         Rails.error.report(e, source: 'spree_bank_payments.poll')
+        report_failure(payment_method)
+      end
+
+      # Deliberately takes no exception: the reason is drawn from a closed enum
+      # and is never derived from what was raised, because an exception message
+      # can carry a bearer token straight into a log aggregator.
+      #
+      # The outer rescue is a backstop only. Reporting health must not depend on
+      # the reconciler being answerable -- see #failure_status.
+      def report_failure(payment_method)
+        status = failure_status(payment_method)
+        reason = status == :consent_revoked ? :consent_revoked : :provider_error
+
+        report_health(payment_method, status, reason)
+      rescue StandardError => e
+        Rails.error.report(e, source: 'spree_bank_payments.health')
+      end
+
+      # Ask the reconciler what kind of failure this was. A provider that knows
+      # its consent is dead says :consent_revoked; everything else is
+      # :transient, including "we could not ask".
+      #
+      # Asking is best-effort, and its failure must never cost us the report.
+      # #health is a real network call for most providers, and an unregistered
+      # reconciler key raises out of Reconcilers::Base.build before #health is
+      # even reached -- which is precisely the case an operator most needs told
+      # about, because Gateway#health deliberately keeps offering bank transfer
+      # in that state. Letting the raise reach report_failure's rescue meant a
+      # store whose provider gem had gone took transfers indefinitely with no
+      # event, no log line and no persisted health_status: the documented
+      # reason=provider_error alert, the thesis of this release, never fired.
+      def failure_status(payment_method)
+        status = begin
+          payment_method.reconciler.health
+        rescue StandardError => e
+          Rails.error.report(e, source: 'spree_bank_payments.health')
+          :transient
+        end
+
+        return :transient unless Reconcilers::Base::HEALTH_STATES.include?(status)
+
+        status == :ok ? :transient : status
+      end
+
+      # Reporting health is bookkeeping about the poll, not part of it. On the
+      # success path the call sits inside poll_one's rescue region, so a
+      # reporter that raised -- a logger blowing up, an event subscriber
+      # exploding -- would have recorded a failure for a poll that fully
+      # succeeded, and then reported health a second time from report_failure.
+      #
+      # An `else` clause on poll_one would move the call out of the rescue
+      # region, but then the exception escapes poll_one entirely and aborts the
+      # find_each over every remaining payment method. Its own rescue is what
+      # contains it, mirroring what report_failure already does.
+      def report_health(payment_method, status, reason)
+        HealthReporter.call(payment_method: payment_method, status: status, reason: reason)
+      rescue StandardError => e
+        Rails.error.report(e, source: 'spree_bank_payments.health')
       end
     end
   end

data/app/models/spree/bank_payments/account_data.rb

@@ -3,9 +3,14 @@ module Spree
     # One account as reported by a provider, in the gem's normalised shape.
     # The reconciler maps its provider's response into this -- the database and
     # views never see provider-specific schemas.
-    AccountData = Data.define(:provider_account_id, :currency, :details) do
-      def initialize(details: [], **rest)
-        super(details: details, **rest)
+    #
+    # `pooled` marks an account whose coordinates are shared with other
+    # customers of the provider, so the payment reference is the only thing
+    # separating two payers. Defaults to false: every provider written before
+    # 5.3.0 omits it, and a dedicated account is the safe assumption.
+    AccountData = Data.define(:provider_account_id, :currency, :details, :pooled) do
+      def initialize(details: [], pooled: false, **rest)
+        super(details: details, pooled: pooled, **rest)
       end
     end
   end

data/app/models/spree/bank_payments/gateway.rb

@@ -15,6 +15,7 @@ module Spree
 
       validate :discount_percent_within_bounds
       validate :expiry_days_positive
+      validate :reconciler_registered
 
       has_many :bank_accounts,
                class_name: 'Spree::BankPayments::BankAccount',
@@ -100,23 +101,61 @@ module Spree
         'spree_bank_payments'
       end
 
+      # Memoized because #health calls it twice and #health runs on every
+      # checkout render for a non-Manual gateway -- unmemoized that was two
+      # round trips per render, and on a gateway that has never polled, two
+      # find_or_create_by! calls.
       def reconciler_state
-        Spree::BankPayments::ReconcilerState.find_or_create_by!(payment_method_id: id)
+        @reconciler_state ||= find_or_create_reconciler_state
       end
 
       def reconciler
         @reconciler ||= Reconcilers::Base.build(payment_method: self)
       end
 
+      # Memoized state must not outlive an explicit reload of the record.
+      def reload(*)
+        @reconciler_state = nil
+        @reconciler = nil
+        super
+      end
+
       # Gate on both the reconciler's own opinion and our recorded poll history.
       # The Manual reconciler is always healthy because it never polls.
+      #
+      # An unbuildable reconciler is unhealthy rather than an exception. Two
+      # callers make that matter: ExpireSessionsJob, which must not cancel
+      # anything while we cannot see the bank, and the payment method's
+      # configuration-guide partial, which Spree renders on the **edit form** --
+      # so raising here locked an admin out of the one screen where an
+      # uninstalled provider gem can be switched back to 'manual'.
       def reconciler_healthy?
-        return false unless reconciler.healthy?
-        return true if reconciler.instance_of?(Reconcilers::Manual)
+        built = safely_built_reconciler
+        return false if built.nil?
+        return false unless built.healthy?
+        return true if built.instance_of?(Reconcilers::Manual)
 
         reconciler_state.healthy?(preferred_poll_interval_minutes)
       end
 
+      # The persisted view of health, safe to call on the checkout hot path.
+      #
+      # Deliberately does NOT call `reconciler.health`: available_for_order? runs
+      # on every checkout render, and a provider's live check is an HTTP request.
+      # The poll job is what refreshes this.
+      #
+      # #reconciler_healthy? is left alone -- it gates the expiry job from a
+      # background worker where a live check is fine, and changing it here would
+      # alter behaviour this task has no reason to touch.
+      def health
+        return :ok if manual_reconciler?
+
+        persisted = reconciler_state.health_status.presence&.to_sym
+        return :consent_revoked if persisted == :consent_revoked
+
+        reconciler_state.healthy?(preferred_poll_interval_minutes) ? :ok : :transient
+      end
+
       # Called by Spree::Api::V3::Webhooks::PaymentsController. Signature
       # verification happens inside the reconciler and raises
       # Spree::PaymentMethod::WebhookSignatureError, which the controller turns
@@ -156,6 +195,11 @@ module Spree
       def available_for_order?(order)
         return false unless super
 
+        # Nothing will ever reconcile against a dead consent, so quoting bank
+        # details would take money we cannot match to an order. :transient is
+        # deliberately not gated here.
+        return false if health == :consent_revoked
+
         return true if offered_account_for(order.currency).present?
 
         # An order that already quoted this gateway must be able to settle
@@ -204,6 +248,70 @@ module Spree
 
       private
 
+      # The first-ever concurrent checkout render on a gateway is a real race:
+      # two requests both miss the SELECT, both INSERT, and the unique index on
+      # payment_method_id makes the loser raise. PollJob already reasons about
+      # this race (its rescue guards a nil `state`); the checkout path did not.
+      # By the time the loser is here the winner has committed a row, so
+      # re-reading it is the whole recovery.
+      def find_or_create_reconciler_state
+        Spree::BankPayments::ReconcilerState.find_or_create_by!(payment_method_id: id)
+      rescue ActiveRecord::RecordNotUnique
+        Spree::BankPayments::ReconcilerState.find_by!(payment_method_id: id)
+      end
+
+      # #health is reached from available_for_order?, which runs on every
+      # checkout render for every customer. Reconcilers::Base.build raises for
+      # a key that is not in the registry -- a typo'd preference, or a provider
+      # gem uninstalled while a gateway still names it -- and before 5.3.0 that
+      # only ever surfaced inside PollJob and ExpireSessionsJob, both of which
+      # rescue per payment method. Letting it escape here would turn a config
+      # mistake into a storefront 500.
+      #
+      # An unbuildable reconciler is therefore simply "not the Manual one", so
+      # #health falls through to the persisted state and reads :transient for a
+      # gateway that has never polled: the payment method keeps being offered
+      # and nothing reconciles, which is exactly what a misconfigured gateway
+      # did before this release. Withdrawing checkout on a config typo would be
+      # a new and much louder failure mode than the one being fixed.
+      def manual_reconciler?
+        safely_built_reconciler.instance_of?(Reconcilers::Manual)
+      end
+
+      # The rescue is deliberately tight around the build itself, and catches
+      # only ArgumentError -- the one Reconcilers::Base.build raises for an
+      # unregistered key. A provider's own constructor blowing up is a bug that
+      # should still surface, not something to fold into "unhealthy".
+      def safely_built_reconciler
+        reconciler
+      rescue ArgumentError
+        nil
+      end
+
+      # Catch the typo where it is made, rather than at the next poll. Skipped
+      # when the value is unchanged on an already-persisted record: if a
+      # provider gem is uninstalled, an admin still has to be able to save this
+      # gateway -- deactivating it, or switching it back to 'manual', is the
+      # recovery, and a validation that refused every save would lock the one
+      # record they need to fix.
+      #
+      # Saving is only half of that recovery: the admin also has to be able to
+      # *open* the edit form, whose configuration-guide partial calls
+      # #reconciler_healthy?. That is why that method tolerates an unbuildable
+      # reconciler too -- without it this escape hatch would let an admin save a
+      # screen they could never reach.
+      def reconciler_registered
+        key = preferred_reconciler.to_s
+        return if Reconcilers::Base.registry.key?(key)
+        return if persisted? && persisted_reconciler_key == key
+
+        errors.add(:preferred_reconciler, :inclusion)
+      end
+
+      def persisted_reconciler_key
+        (preferences_in_database || {}).with_indifferent_access[:reconciler].to_s
+      end
+
       def discount_percent_within_bounds
         percent = preferred_discount_percent.to_d
         return if percent >= 0 && percent <= 100

data/app/models/spree/bank_payments/reconciler_state.rb

@@ -21,6 +21,16 @@ module Spree
       def record_failure!(error)
         update!(last_error: error.to_s.truncate(1000), consecutive_failures: consecutive_failures + 1)
       end
+
+      # @param status [Symbol] a member of Reconcilers::Base::HEALTH_STATES
+      # @param reason [Symbol] a member of HealthReporter::REASONS
+      # @param logged [Boolean] whether this report was actually emitted
+      def record_health!(status:, reason:, logged:)
+        attrs = { health_status: status.to_s, health_reason: reason.to_s }
+        attrs[:health_reported_at] = Time.current if logged
+
+        update!(attrs)
+      end
     end
   end
 end

data/app/models/spree/bank_payments/reconcilers/base.rb

@@ -41,9 +41,34 @@ module Spree
           raise NotImplementedError, "#{self.class} must implement #parse_webhook"
         end
 
+        HEALTH_STATES = %i[ok transient consent_revoked].freeze
+
+        # @return [Symbol] one of HEALTH_STATES.
+        #
+        # :transient still offers at checkout -- a brief provider outage must
+        # not pull bank transfer off the storefront, because the money still
+        # arrives and reconciles once the provider returns. Only
+        # :consent_revoked withdraws it, because in that state nothing will
+        # ever reconcile.
+        #
+        # Providers written against <= 5.2 implement #healthy? only, so the
+        # default derives from it.
+        def health
+          healthy? ? :ok : :transient
+        end
+
         # @return [Boolean] false means the expiry job must not cancel anything
+        #
+        # Providers written against >= 5.3 may implement #health only, so the
+        # default derives from it. The two defaults are mutually recursive by
+        # construction; the owner check breaks the cycle and turns "overrode
+        # neither" into a clear contract error instead of a SystemStackError.
         def healthy?
-          raise NotImplementedError, "#{self.class} must implement #healthy?"
+          if method(:health).owner == Spree::BankPayments::Reconcilers::Base
+            raise NotImplementedError, "#{self.class} must implement #health or #healthy?"
+          end
+
+          health == :ok
         end
 
         # @return [Boolean] whether credentials and settings are complete

data/app/models/spree/bank_payments/reconcilers/manual.rb

@@ -12,8 +12,10 @@ module Spree
           nil
         end
 
-        def healthy?
-          true
+        # The manual reconciler never talks to anything, so it cannot be
+        # unhealthy.
+        def health
+          :ok
         end
 
         def configured?

data/app/services/spree/bank_payments/health_reporter.rb

@@ -0,0 +1,122 @@
+module Spree
+  module BankPayments
+    # Owns the health log line and its event, for every provider.
+    #
+    # This lives in core rather than in each provider gem on purpose: health
+    # already gates checkout and the expiry job, so if providers each logged
+    # their own way, every new provider would reinvent it and every downstream
+    # alert rule would need another clause.
+    class HealthReporter
+      RELOG_AFTER = 1.hour
+
+      # A closed set. A provider hands us one of these symbols; anything else
+      # becomes :unknown. Reasons are NEVER built from an exception message or
+      # a response body -- that is how a bearer token reaches a log aggregator.
+      #
+      # Deliberately only the four values core can actually produce. Widening a
+      # published enum later is non-breaking; narrowing it is not, and every
+      # value here is a promise to alert rules that key on reason=. Nothing
+      # hands a provider a way to supply its own reason yet, so a richer
+      # vocabulary would be advertising states no code path can reach.
+      REASONS = %i[ok provider_error consent_revoked unknown].freeze
+
+      def self.call(payment_method:, status:, reason:)
+        new(payment_method: payment_method, status: status, reason: reason).call
+      end
+
+      def initialize(payment_method:, status:, reason:)
+        @payment_method = payment_method
+        @status = clamp(status.to_s.to_sym, Reconcilers::Base::HEALTH_STATES, :transient)
+        @reason = clamp(reason.to_s.to_sym, REASONS, :unknown)
+      end
+
+      def call
+        logged = should_log?
+        emit if logged
+        state.record_health!(status: status, reason: reason, logged: logged)
+        logged
+      end
+
+      private
+
+      attr_reader :payment_method, :status, :reason
+
+      # `reason` was already clamped; `status` was not, so an unrecognised one
+      # fell through the severity ternary to WARN and was persisted verbatim
+      # into health_status -- where Gateway#health then reads it. :transient is
+      # the fallback because it preserves that de-facto WARN severity while
+      # keeping the persisted value inside HEALTH_STATES. :ok would claim a
+      # health we have no evidence for, and :consent_revoked would withdraw the
+      # payment method from checkout on nothing more than a typo.
+      def clamp(value, permitted, fallback)
+        permitted.include?(value) ? value : fallback
+      end
+
+      def state
+        @state ||= payment_method.reconciler_state
+      end
+
+      def previous
+        @previous ||= state.health_status.presence&.to_sym
+      end
+
+      def changed?
+        previous.present? && previous != status
+      end
+
+      def due?
+        state.health_reported_at.nil? || state.health_reported_at < RELOG_AFTER.ago
+      end
+
+      def should_log?
+        return changed? if status == :ok
+
+        changed? || due?
+      end
+
+      def emit
+        status == :ok ? emit_recovered : emit_unhealthy
+      end
+
+      def emit_unhealthy
+        severity = status == :consent_revoked ? :error : :warn
+
+        Rails.logger.public_send(severity, <<~LINE.squish)
+          [spree-bank_payments] reconciler unhealthy
+          event=bank_transfer.reconciler_health.unhealthy
+          reconciler=#{payment_method.preferred_reconciler}
+          payment_method_id=#{payment_method.id}
+          status=#{status}
+          reason=#{reason}
+          consecutive_failures=#{state.consecutive_failures}
+          last_success_at=#{state.last_successful_run_at&.iso8601 || 'never'}
+        LINE
+
+        publish('bank_transfer.reconciler_health.unhealthy')
+      end
+
+      def emit_recovered
+        Rails.logger.info(<<~LINE.squish)
+          [spree-bank_payments] reconciler recovered
+          event=bank_transfer.reconciler_health.recovered
+          reconciler=#{payment_method.preferred_reconciler}
+          payment_method_id=#{payment_method.id}
+          previous_status=#{previous}
+        LINE
+
+        publish('bank_transfer.reconciler_health.recovered')
+      end
+
+      # Serializable primitives only: subscribers run async through ActiveJob
+      # and an ActiveRecord object cannot survive the trip.
+      def publish(event)
+        Spree::Events.publish(event,
+                              payment_method_id: payment_method.id,
+                              reconciler: payment_method.preferred_reconciler.to_s,
+                              status: status.to_s,
+                              reason: reason.to_s,
+                              consecutive_failures: state.consecutive_failures)
+      end
+    end
+  end
+end

data/app/services/spree/bank_payments/sync_accounts.rb

@@ -84,6 +84,7 @@ module Spree
               provider_account_id: data.provider_account_id,
               currency: data.currency,
               details: data.details,
+              pooled: data.pooled,
               offered: false,
               active: true,
               synced_at: Time.current
@@ -92,7 +93,7 @@ module Spree
 
           prepared[:update].each do |data|
             account = payment_method.bank_accounts.find_by(provider_account_id: data.provider_account_id)
-            account.update!(currency: data.currency, details: data.details,
+            account.update!(currency: data.currency, details: data.details, pooled: data.pooled,
                             active: true, synced_at: Time.current)
           end
 

data/app/views/spree/admin/bank_accounts/index.html.erb

@@ -35,7 +35,12 @@
 
 <table class="table">
   <thead>
-    <tr><th>Currency</th><th>Account</th><th>Source</th><th>Offered</th><th>Active</th><th></th></tr>
+    <%# `Pooled` is a provider-reported fact, not an admin choice, so it renders
+        as a plain cell like `Active` rather than a toggle. It is shown because
+        it changes how a human must read the hand-match queue: on a pooled
+        account the coordinates are shared with other customers of the
+        provider, so the reference is the only thing identifying the payer. %>
+    <tr><th>Currency</th><th>Account</th><th>Source</th><th>Offered</th><th>Active</th><th>Pooled</th><th></th></tr>
   </thead>
   <tbody>
     <% @bank_accounts.each do |account| %>
@@ -55,6 +60,14 @@
                         class: account.offered? ? 'btn btn-sm btn-success' : 'btn btn-sm btn-outline-secondary' %>
         </td>
         <td><%= account.active? ? 'Yes' : 'No' %></td>
+        <td>
+          <% if account.pooled? %>
+            <span class="badge bg-warning text-dark"
+                  title="These coordinates are shared with other customers of the provider. The payment reference is the only thing identifying the payer.">Pooled</span>
+          <% else %>
+            No
+          <% end %>
+        </td>
         <td>
           <% unless account.synced? %>
             <%= link_to 'Edit', spree.edit_admin_payment_method_bank_account_path(@payment_method, account) %>

data/app/views/spree/admin/bank_transfers/index.html.erb

@@ -23,6 +23,22 @@
           <td><%= transfer.payer_name %></td>
           <td><code><%= transfer.reference_raw.presence || '—' %></code></td>
           <td>
+            <%# Suggestions are ranked partly on fuzzy pg_trgm payer-name
+                similarity, so a plausible-looking name is not evidence of who
+                paid. On a pooled account it is not evidence at all: every
+                customer of the provider sends to the same coordinates, so two
+                unrelated payers land here indistinguishable except by the
+                reference they quoted. Say so on the screen where the admin is
+                about to click, not only on the accounts screen. %>
+            <% if transfer.bank_account&.pooled? %>
+              <div class="alert alert-warning py-1 px-2 mb-2">
+                <strong>Pooled account.</strong> These coordinates are shared
+                with other customers of the provider, so the reference is the
+                only thing identifying who paid. Check the reference above
+                against the order before applying — a suggestion here is a
+                guess, not a match.
+              </div>
+            <% end %>
             <% Array(@suggestions[transfer.id]).each do |suggestion| %>
               <%# Currency compared case-insensitively, matching the controller's
                   own casecmp guard -- otherwise 'gbp' vs 'GBP' (the same

data/db/migrate/20260817000007_add_health_to_reconciler_states.rb

@@ -0,0 +1,7 @@
+class AddHealthToReconcilerStates < ActiveRecord::Migration[7.2]
+  def change
+    add_column :spree_bank_payments_reconciler_states, :health_status, :string
+    add_column :spree_bank_payments_reconciler_states, :health_reason, :string
+    add_column :spree_bank_payments_reconciler_states, :health_reported_at, :datetime
+  end
+end

data/db/migrate/20260817000008_add_pooled_to_bank_accounts.rb

@@ -0,0 +1,5 @@
+class AddPooledToBankAccounts < ActiveRecord::Migration[7.2]
+  def change
+    add_column :spree_bank_payments_bank_accounts, :pooled, :boolean, null: false, default: false
+  end
+end

data/lib/spree/bank_payments/testing_support/reconciler_shared_examples.rb

@@ -30,6 +30,10 @@ RSpec.shared_examples 'a bank transfer reconciler' do
     expect([true, false]).to include(reconciler.healthy?)
   end
 
+  it 'answers #health with a member of the published enum' do
+    expect(Spree::BankPayments::Reconcilers::Base::HEALTH_STATES).to include(reconciler.health)
+  end
+
   it 'answers #configured? with a boolean' do
     expect([true, false]).to include(reconciler.configured?)
   end

data/lib/spree/bank_payments/version.rb

@@ -1,6 +1,6 @@
 module Spree
   module BankPayments
     # Major version tracks Spree's major version: 5.x supports Spree 5.x.
-    VERSION = '5.2.0'.freeze
+    VERSION = '5.3.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree-bank_payments
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.3.0
 platform: ruby
 authors:
 - Aypex
@@ -98,6 +98,7 @@ files:
 - app/models/spree/payment_sessions/bank_transfer.rb
 - app/services/spree/bank_payments/apply_discount.rb
 - app/services/spree/bank_payments/apply_transfer.rb
+- app/services/spree/bank_payments/health_reporter.rb
 - app/services/spree/bank_payments/ingest_transfer.rb
 - app/services/spree/bank_payments/migrate_legacy_accounts.rb
 - app/services/spree/bank_payments/reference_generator.rb
@@ -128,6 +129,8 @@ files:
 - db/migrate/20260817000003_exclude_soft_deleted_from_bank_account_uniqueness.rb
 - db/migrate/20260817000004_migrate_legacy_account_preferences.rb
 - db/migrate/20260817000006_add_bank_account_id_to_sessions_and_transfers.rb
+- db/migrate/20260817000007_add_health_to_reconciler_states.rb
+- db/migrate/20260817000008_add_pooled_to_bank_accounts.rb
 - lib/generators/spree/bank_payments/install/install_generator.rb
 - lib/spree-bank_payments.rb
 - lib/spree/bank_payments.rb