spree-bank_payments 5.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62489d37734d726a1b9fa5c30303ccd5165ed2679c18e1e87fe69dbddc25d446
+  data.tar.gz: 502281b05bf1680cf13c92ac26e96fb51d5216e513830ae59e0301c66334ee17
+SHA512:
+  metadata.gz: 8a81d4f37d6ccf997de25c8dfadb60c73cc91a0812851bdd5477acc2b323948648e19a7469bf861201cde794984ce9eb962b1d2991aae111f59c6b3ec47ea342
+  data.tar.gz: 16684728ff3aace5f8fabac9c2b48766a044ae9c2dd6d9dd904da5755051156af04e53369e2535e34e069641d2654db61ceec966f32e98bd014d56beb40ef28c

data/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 5.0.0
+
+First public release on RubyGems, as `spree-bank_payments`.
+
+This gem was developed under the working names `aypex_bank_transfer`,
+`spree_bank_transfer` and `spree_bank_payments`, but was never published under any
+of them.
+
+Every spelling of `bank_transfer` turned out to be unavailable. Two different
+owners hold the underscore and hyphen forms — `spree_bank_transfer` (vinsol, 2013)
+and `spree-bank-transfer` (Mohit Bansal, 2014) — and `spree-bank_transfer` is
+rejected too, because RubyGems refuses a new name that is too similar to an
+existing one and treats `-` and `_` as equivalent. An API 404 on a gem name means
+"no exact match", not "publishable".
+
+`spree-bank_payments` is free, and the spelling is correct on its own terms: a dash
+denotes a gem under another gem's namespace while an underscore joins words within
+one level, so the gem name, the require path (`spree/bank_payments`) and the Ruby
+namespace (`Spree::BankPayments`) all agree.
+
+The *domain* vocabulary is still "bank transfer" — that is what the payment
+instrument is. Only the gem namespace is `BankPayments`.
+
+**Versioning:** the major version tracks Spree's major version — `spree-bank_payments`
+5.x supports Spree 5.x. The gemspec requires `spree >= 5.6.0`.
+
+If you tracked this repository from git before 5.0.0, note:
+
+- **Gem name** is `spree-bank_payments`. `gem 'spree-bank_payments'` is all a host
+  app needs — `Bundler.require` resolves through a shim at `lib/spree-bank_payments.rb`.
+- **Require path** is now `spree/bank_payments`.
+- **Ruby namespace** is now `Spree::BankPayments` (was the top-level `SpreeBankPayments`).
+  Note the nesting change: these constants now live under `Spree`.
+- **Install generator** is now `rails g spree:bank_payments:install`.
+- **Database tables** are `spree_bank_payments_incoming_transfers` and
+  `spree_bank_payments_reconciler_states`. The migrations were edited in place
+  rather than shipped as renames, which is safe only because no host application
+  had ever run them. There is no upgrade path from an earlier checkout that had
+  already migrated — drop the old tables and re-run.
+- **Unchanged:** `Spree::PaymentSessions::BankTransfer`,
+  `Spree::Admin::BankTransfersController`, `IncomingTransfer`, `TransferData`, and
+  the admin routes.
+
+`engine_name` is `spree_bank_payments`: it generates route helper prefixes and the
+`spree_bank_payments:install:migrations` rake task, so it must be a valid Ruby
+identifier and cannot take a dash.
+
+### Features
+
+- Bank transfer payment method with a configurable checkout discount, expiry
+  window, and unique per-order payment references.
+- Pluggable reconciliation of incoming transfers, with a manual reconciler that
+  works out of the box and a documented interface for bank-specific backends.
+- Admin queue for transfers that cannot be matched automatically, with match
+  suggestions backed by `pg_trgm` similarity.
+- Instruction and reminder mailers, session expiry, and polling jobs.
+- PostgreSQL only: `jsonb`, partial unique indexes and `pg_trgm` are load-bearing.

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Aypex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,213 @@
+# spree-bank_payments
+
+Bank transfer checkout for Spree 5.6+, with pluggable reconciliation of
+incoming payments.
+
+## Requirements
+
+PostgreSQL. The gem uses `jsonb`, partial unique indexes, and `pg_trgm`.
+
+## Installation
+
+```ruby
+gem 'spree-bank_payments'
+```
+
+```bash
+bundle install
+bin/rails g spree:bank_transfer:install
+```
+
+The generator copies the migrations and then asks whether to run them. Pass
+`--auto-run-migrations` to skip the prompt (useful in scripted installs).
+
+## Configuration
+
+Add a Bank Transfer payment method in the Spree admin and set:
+
+| Preference | Purpose |
+|---|---|
+| `reconciler` | `manual` by default; `revolut` with `spree-bank_payments_revolut` installed |
+| `reference_prefix` | Prefix on generated references, e.g. `TKF-` |
+| `expiry_days` | Days before an unpaid order is cancelled and restocked |
+| `discount_percent` | Percentage off `item_total` for paying by transfer |
+| `poll_interval_minutes` | How often the reconciler polls; drives the health gate |
+| `account_*` | Bank details shown to the customer |
+
+## The admin queue and the manual workflow
+
+The gem adds a **Bank transfers** entry to the Spree admin sidebar, pointing
+at `/admin/bank_transfers`. That screen is the operational heart of the gem:
+
+- **The unmatched queue** (`/admin/bank_transfers`) lists every observed
+  transfer that hasn't been matched to an order, with suggested sessions
+  ranked by exact amount first and fuzzy payer-name similarity second. Apply
+  a suggestion in one click, or ignore the transfer with a reason.
+- **Record a received transfer** (`/admin/bank_transfers/new`) is how money
+  gets into the system when you're not running a provider integration. This
+  is **required reading if you use the default `manual` reconciler**: it has
+  nothing to poll and no webhook, so this form is the only way a transfer can
+  ever be recorded. You enter the payment method, amount, currency, payer
+  name, the reference as the customer quoted it, and the date received; the
+  entry then goes through exactly the same matching path as a
+  provider-delivered transfer. An exact match (reference, amount, currency,
+  against a single open session on an unpaid order) applies immediately and
+  marks the order paid. Anything else lands in the queue above.
+
+  Submitting the same form twice is safe: the transfer's identity is derived
+  from what you typed, so a resubmission is recognised as the same transfer
+  and nothing is credited twice.
+
+- **Applying to a mismatched order** takes two deliberate steps. The first
+  click is refused with both amounts spelled out; only then does an explicit
+  "Yes — apply … anyway" control appear for that specific pairing, behind a
+  confirmation dialog. A mismatch is credited for the amount that actually
+  arrived, so the order lands in `balance_due`/`credit_owed` rather than a
+  false `paid`.
+
+### The order panel partial
+
+`spree/bank_payments/admin/_order_panel` renders the bank-transfer state for
+a single order — reference, amount, status, expiry, and the matched transfer
+if there is one. The gem does **not** inject it anywhere; render it from your
+admin order view where it makes sense for your store:
+
+```erb
+<%= render 'spree/bank_payments/admin/order_panel', order: @order %>
+```
+
+## Scheduling
+
+These scheduled jobs are mandatory, not optional — without them nothing
+expires and no reminders send:
+
+| Job | Frequency | Purpose |
+|---|---|---|
+| `Spree::BankPayments::ExpireSessionsJob` | Hourly | Cancels and restocks orders whose payment window has lapsed |
+| `Spree::BankPayments::SendRemindersJob` | Daily | Sends payment reminders as the expiry deadline approaches |
+| `Spree::BankPayments::PollJob` | Every `poll_interval_minutes` (default 15) | Polls the configured reconciler for new transfers; a successful run is what arms the health gate below |
+
+Wire all three into your scheduler (`sidekiq-cron`, `whenever`, etc.) as part
+of installing this gem, not as an afterthought.
+
+## The health gate
+
+`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
+credential lapses or a webhook silently stops arriving, the reconciler stops
+confirming payments, but orders keep aging past their expiry window. Without
+the gate, `ExpireSessionsJob` would start cancelling and restocking orders
+for customers who have already paid — just because the gem couldn't see the
+payment. Instead, a stale reconciler raises an alert and the job cancels
+nothing.
+
+Subscribe to `bank_transfer.reconciler_unhealthy` and route it somewhere a
+human will see it. A lapsed credential is an operational incident, not
+background noise.
+
+`ExpireSessionsJob` also leaves alone any order that has already been paid by
+other means — a customer who abandons the transfer and pays by card keeps a
+stale open session, and cancelling it would cancel and restock a paid order.
+Those sessions are closed as `canceled` and
+`bank_transfer.session_superseded` is published instead. For the same reason
+a transfer that arrives against an already-paid order is never auto-applied:
+it queues for a human, because a second payment on a settled order is a
+decision, not a reconciliation.
+
+## Events
+
+The gem never sends notifications directly — it publishes to
+`Spree::Events`, and subscribers decide what to do:
+
+| Event | Fired when |
+|---|---|
+| `bank_transfer.instructions_ready` | A payment session is created and the customer needs the reference/bank details |
+| `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.expiry_failed` | `ExpireSessionsJob` hits an error cancelling a specific session |
+
+Payloads contain serializable primitives only — never AR objects — because
+subscribers may run async via ActiveJob. See
+`Spree::PaymentSessions::BankTransfer#notification_payload` for the exact
+shape. Subscribe with `Spree::Events.subscribe('bank_transfer.*', MyHandler)`
+or to individual event names.
+
+A bundled mailer subscribes to `instructions_ready` and `reminder_due` as one
+optional subscriber among possibly several. Disable it with:
+
+```ruby
+Spree::BankPayments::Config.disable_default_mailer = true
+```
+
+Stores that deliver mail another way — for example a storefront webhook
+handler that calls out to Postmark/Resend/etc. rather than using
+ActionMailer — should disable the default mailer and subscribe to the events
+directly instead of fighting the bundled one.
+
+## Known limitations
+
+**The discount does not affect tax on a tax-inclusive (VAT) store.**
+
+`discount_percent` is applied as a single order-level `Spree::Adjustment`
+against `order.item_total`. Spree computes `taxable_adjustment_total` by
+summing tax-relevant adjustments on *line items and shipments only* — an
+order-level adjustment is never included in that sum. The practical effect:
+on a VAT store, the customer pays less, but the order still records tax as
+if calculated on the undiscounted price. The discount and the tax figure
+disagree.
+
+This is not a bug we plan to quietly patch later — fixing it properly means
+moving the discount onto line-item adjustments, the way Spree's own
+promotions do, which is a bigger change than this gem currently makes. If
+your store is VAT/tax-inclusive, know this before you set a
+`discount_percent`, and evaluate whether the mismatch is acceptable for your
+accounting.
+
+## The instructions partial ships no CSS
+
+`spree/bank_payments/_order_instructions` renders the payment reference and
+bank details with no styling of its own. Making the reference visually
+prominent — the single most impactful thing you can do for match rates — is
+the host store's responsibility. Customers who don't notice or don't copy
+the reference correctly produce transfers reconciliation can't match
+automatically, which means manual admin work. Style it like the most
+important line on the page, because for a bank-transfer checkout, it is.
+
+## Writing a reconciler
+
+Subclass `Spree::BankPayments::Reconcilers::Base` and implement the four
+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
+- `#configured?` — boolean; whether credentials/settings are complete
+
+Register it:
+
+```ruby
+Spree::BankPayments::Reconcilers::Base.register('my_bank', MyBank::Reconciler)
+```
+
+and run **both** shared example groups against it — not just the first one:
+
+```ruby
+require 'spree/bank_payments/testing_support/reconciler_shared_examples'
+
+RSpec.describe MyBank::Reconciler do
+  let(:payment_method) { create(:bank_transfer_gateway) }
+
+  it_behaves_like 'a bank transfer reconciler'
+  it_behaves_like 'a bank transfer reconciler that returns transfers'
+end
+```
+
+The second group exists because the first can't check element types: a
+reconciler with nothing to poll legitimately returns `[]`, and any
+`all(be_a(...))` assertion passes vacuously against an empty array. The
+second group requires `#poll` to return at least one real `TransferData` and
+checks its shape — that's the only way to actually exercise the type
+contract.

data/Rakefile

@@ -0,0 +1,36 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+RSpec::Core::RakeTask.new
+
+task :default do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+  Rake::Task[:spec].invoke
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  # Must be the require path, not the gem name: spree_core's common:test_app does a
+  # literal `require ENV['LIB_NAME']`, templates the same string into the generated
+  # dummy app, and constantizes "#{LIB_NAME.camelize}::Generators::InstallGenerator"
+  # -- which only resolves to Spree::BankPayments::Generators::InstallGenerator when
+  # this is the slash form.
+  ENV['LIB_NAME'] = 'spree/bank_payments'
+  # This gem is PostgreSQL-only: jsonb, partial indexes and pg_trgm are all
+  # load-bearing. Default the harness accordingly so a bare `rake test_app`
+  # cannot silently build a SQLite app on which none of them are real.
+  ENV['DB'] ||= 'postgres'
+  # extension:test_app (spree_core) generates the dummy app, migrates Spree's own
+  # schema, then auto-loads generators/spree/bank_payments/install/install_generator
+  # and runs it with --auto-run-migrations. That generator copies *only* this gem's
+  # migrations (scoped via `rake spree_bank_payments:install:migrations`, not the
+  # unscoped `railties:install:migrations`) and runs db:migrate, so a fresh
+  # `rake test_app` needs no manual migration step.
+  Rake::Task['extension:test_app'].execute(install_storefront: true, install_admin: true)
+end

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

@@ -0,0 +1,287 @@
+module Spree
+  module Admin
+    class BankTransfersController < Spree::Admin::BaseController
+      include Pagy::Method
+
+      # Synthetic provider for transfers an admin typed in by hand. Keeps
+      # them distinguishable from anything a real reconciler delivered, and
+      # gives the (provider, provider_transaction_id) uniqueness index its
+      # own namespace so a hand-entered row can never collide with a
+      # provider-issued transaction id.
+      MANUAL_PROVIDER = 'manual'.freeze
+
+      before_action :load_transfer, only: %i[apply ignore]
+      before_action :load_recordable_payment_methods, only: %i[new create]
+
+      def index
+        @pagy, @transfers = pagy(
+          Spree::BankPayments::IncomingTransfer.unmatched.order(occurred_at: :desc)
+        )
+
+        @suggestions = @transfers.each_with_object({}) do |transfer, acc|
+          acc[transfer.id] = Spree::BankPayments::SuggestMatches.new(transfer: transfer).call
+        end
+
+        # Set only by #apply's mismatch refusal (see I3). Identifies the one
+        # transfer/session pair the admin has already been shown the numbers
+        # for and may now confirm.
+        @confirm_transfer_id = params[:confirm_transfer_id].presence&.to_i
+        @confirm_payment_session_id = params[:confirm_payment_session_id].presence&.to_i
+      end
+
+      # "Record a received transfer". The Manual reconciler -- the default,
+      # and the only one this gem ships -- returns [] from #poll and nil from
+      # #parse_webhook, so nothing else can ever create an IncomingTransfer.
+      # Without this form a store on the shipped configuration takes a
+      # customer's money and has no action available to record it, and
+      # ExpireSessionsJob cancels the order a few days later.
+      def new
+        @transfer_form = blank_transfer_form
+      end
+
+      # Deliberately builds a TransferData and hands it to IngestTransfer
+      # rather than writing an IncomingTransfer directly: matching lives in
+      # exactly one place, so a hand-recorded transfer behaves identically to
+      # a provider-delivered one -- exact match auto-applies, anything else
+      # lands in the queue for a human.
+      def create
+        @transfer_form = transfer_form_params
+
+        error = transfer_form_error(@transfer_form)
+        if error
+          flash.now[:error] = error
+          return render :new, status: :unprocessable_entity
+        end
+
+        payment_method = @payment_methods.detect { |pm| pm.id.to_s == @transfer_form[:payment_method_id].to_s }
+        transaction_id = manual_transaction_id(payment_method, @transfer_form)
+
+        # The idempotency guard is IngestTransfer's find_or_create_by! on
+        # (provider, provider_transaction_id). A hand-typed transfer has no
+        # provider-issued id to key on, so we derive a deterministic one from
+        # the submitted facts: an admin who double-submits the form (double
+        # click, browser back-and-resubmit) reproduces the same digest, hits
+        # the existing row, and applies nothing a second time. The trade is
+        # that two genuinely distinct but byte-identical transfers on the
+        # same day collapse into one -- rare, and far safer than the
+        # alternative of crediting an order twice.
+        already_recorded = Spree::BankPayments::IncomingTransfer.exists?(
+          provider: MANUAL_PROVIDER, provider_transaction_id: transaction_id
+        )
+
+        transfer = Spree::BankPayments::IngestTransfer.new(
+          payment_method: payment_method,
+          transfer_data: Spree::BankPayments::TransferData.new(
+            provider: MANUAL_PROVIDER,
+            provider_transaction_id: transaction_id,
+            amount: BigDecimal(@transfer_form[:amount].to_s),
+            currency: @transfer_form[:currency].to_s.strip.upcase,
+            reference: @transfer_form[:reference].to_s.strip,
+            payer_name: @transfer_form[:payer_name].to_s.strip.presence,
+            occurred_at: parse_occurred_at(@transfer_form[:occurred_at]),
+            raw: {
+              'source' => 'admin_manual_entry',
+              'recorded_by_id' => try_spree_current_user&.id
+            }
+          )
+        ).call
+
+        flash[:success] =
+          if already_recorded
+            'That transfer was already recorded — nothing was applied a second time.'
+          elsif transfer.applied?
+            "Transfer recorded and applied to order #{transfer.payment_session&.order&.number}."
+          else
+            'Transfer recorded. It is waiting in the queue below for a match.'
+          end
+
+        redirect_to spree.admin_bank_transfers_path
+      end
+
+      def apply
+        if @transfer.applied?
+          flash[:error] = 'That transfer has already been applied.'
+          return redirect_to spree.admin_bank_transfers_path
+        end
+
+        payment_session = find_bank_transfer_payment_session(params[:payment_session_id])
+
+        if payment_session.nil?
+          flash[:error] = 'That payment session could not be found.'
+          return redirect_to spree.admin_bank_transfers_path
+        end
+
+        if gateway_mismatch?(payment_session)
+          flash[:error] = 'That transfer was received on a different bank-transfer gateway ' \
+                           'and cannot be applied to this session.'
+          return redirect_to spree.admin_bank_transfers_path
+        end
+
+        # I3: the refusal now hands back the pair that needs confirming, and
+        # the queue renders a distinct, explicitly-labelled confirm button
+        # only for that pair. Confirmation is therefore a genuine second
+        # step -- a deliberate act after seeing the numbers -- rather than
+        # something the view pre-granted before the admin looked at anything.
+        if money_mismatch?(payment_session) && !confirmed_mismatch?
+          flash[:error] = "Amount/currency mismatch: the transfer is #{@transfer.money}, " \
+                           "the session expects #{payment_session.money}. " \
+                           'Confirm to apply anyway.'
+          return redirect_to spree.admin_bank_transfers_path(
+            confirm_transfer_id: @transfer.id,
+            confirm_payment_session_id: payment_session.id
+          )
+        end
+
+        Spree::BankPayments::ApplyTransfer.call(
+          transfer: @transfer,
+          payment_session: payment_session,
+          applied_by: try_spree_current_user
+        )
+
+        flash[:success] = 'Payment applied.'
+        redirect_to spree.admin_bank_transfers_path
+      end
+
+      def ignore
+        if @transfer.applied?
+          flash[:error] = 'That transfer has already been applied and cannot be ignored.'
+          return redirect_to spree.admin_bank_transfers_path
+        end
+
+        reason = params[:reason].to_s.strip
+        if reason.blank?
+          flash[:error] = 'A reason is required to ignore a transfer.'
+          return redirect_to spree.admin_bank_transfers_path
+        end
+
+        @transfer.update!(state: 'ignored', ignored_reason: reason)
+
+        flash[:success] = 'Transfer ignored.'
+        redirect_to spree.admin_bank_transfers_path
+      end
+
+      private
+
+      def load_transfer
+        @transfer = Spree::BankPayments::IncomingTransfer.find(params[:id])
+      end
+
+      # Same store guard as the apply path: an admin must not be able to
+      # record a transfer against another store's gateway.
+      def load_recordable_payment_methods
+        @payment_methods = Spree::BankPayments::Gateway.where(store_id: current_store.id).order(:name).to_a
+      end
+
+      def blank_transfer_form
+        {
+          payment_method_id: @payment_methods.first&.id,
+          amount: nil,
+          currency: current_store.default_currency,
+          payer_name: nil,
+          reference: nil,
+          occurred_at: Time.zone.today.to_s
+        }
+      end
+
+      def transfer_form_params
+        params.
+          fetch(:bank_transfer, {}).
+          permit(:payment_method_id, :amount, :currency, :payer_name, :reference, :occurred_at).
+          to_h.
+          symbolize_keys
+      end
+
+      def transfer_form_error(form)
+        return 'No bank-transfer payment method is configured for this store.' if @payment_methods.empty?
+
+        unless @payment_methods.any? { |pm| pm.id.to_s == form[:payment_method_id].to_s }
+          return 'Choose which bank-transfer payment method received this money.'
+        end
+
+        amount = begin
+          BigDecimal(form[:amount].to_s)
+        rescue ArgumentError, TypeError
+          nil
+        end
+        return 'Enter the amount that arrived, as a number.' if amount.nil?
+        return 'The amount that arrived must be greater than zero.' unless amount.positive?
+
+        return 'Enter the currency the money arrived in.' if form[:currency].to_s.strip.blank?
+        return 'Enter the date the money was received.' if parse_occurred_at(form[:occurred_at]).nil?
+
+        nil
+      end
+
+      def parse_occurred_at(value)
+        return nil if value.to_s.strip.blank?
+
+        Time.zone.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      # Deterministic, so a resubmitted form is a no-op rather than a second
+      # credit. Reference is normalised the same way IncomingTransfer
+      # normalises it, and payer name is case/whitespace folded, so trivial
+      # retyping differences still collapse onto the same transfer.
+      def manual_transaction_id(payment_method, form)
+        digest = Digest::SHA256.hexdigest(
+          [
+            payment_method.id,
+            BigDecimal(form[:amount].to_s).to_s('F'),
+            form[:currency].to_s.strip.upcase,
+            Spree::BankPayments::IncomingTransfer.normalize_reference(form[:reference]),
+            form[:payer_name].to_s.strip.downcase,
+            parse_occurred_at(form[:occurred_at]).to_date.iso8601
+          ].join('|')
+        )
+
+        "#{MANUAL_PROVIDER}-#{digest[0, 32]}"
+      end
+
+      # Scoped to the concrete bank-transfer STI subtype and to orders in the
+      # current store, so a `payment_session_id` for another payment method
+      # (credit card, PayPal, ...) or another store cannot be handed to
+      # ApplyTransfer -- that would complete an arbitrary payment/session
+      # pair with real money moving behind it.
+      def find_bank_transfer_payment_session(id)
+        ::Spree::PaymentSessions::BankTransfer.
+          joins(:order).
+          where(spree_orders: { store_id: current_store.id }).
+          find_by(id: id)
+      end
+
+      # The auto-apply path (IngestTransfer) guards on payment_method_id at
+      # the query level, since it starts from a known gateway. The admin
+      # path starts from a payment_session_id typed by a human, so it has
+      # to check the reverse direction explicitly: a transfer received on
+      # one bank-transfer gateway (e.g. a different `provider`) must not be
+      # applicable to a session belonging to another gateway in the same
+      # store. A transfer with no known payment_method (legacy/manual data)
+      # can't be checked and is allowed through -- that's an existing gap,
+      # not a new one.
+      def gateway_mismatch?(payment_session)
+        @transfer.payment_method_id.present? &&
+          @transfer.payment_method_id != payment_session.payment_method_id
+      end
+
+      # A human is allowed to hand-match a transfer to a session for a
+      # different amount/currency (typos happen, partial payments happen)
+      # but never silently -- ApplyTransfer now credits the payment with
+      # the transfer's own amount, so a confirmed mismatch produces a real
+      # balance_due/credit_owed rather than a false 'paid', but the admin
+      # still has to see and confirm the mismatch before it happens.
+      # Currency codes are compared case-insensitively so 'gbp' vs 'GBP'
+      # (same currency, different casing) doesn't force a spurious
+      # confirmation on an otherwise exact match.
+      def money_mismatch?(payment_session)
+        @transfer.amount != payment_session.amount ||
+          @transfer.currency.to_s.casecmp(payment_session.currency.to_s) != 0
+      end
+
+      def confirmed_mismatch?
+        ActiveModel::Type::Boolean.new.cast(params[:confirm_mismatch])
+      end
+    end
+  end
+end