spree-bank_payments 5.1.1 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 853a5591445f34c158831ce573209a2d0bd300c01f107576eecbab2d5c1336d2
-  data.tar.gz: 33614d35672725463dbbb13c1a70398d843135cc824e76ec4e3b3f8ff8b843e9
+  metadata.gz: b7bb0454adf07aad2127a114af121975941265c60b04ba329aa870d5bed31243
+  data.tar.gz: 887a05355e75ae225476c219f4b355dae87354c0e026e5f92bbe1bf56a46bf14
 SHA512:
-  metadata.gz: e35bb75965fe3896265cec76c1f93f117e52b23e2058d9105fdfef973a0c859fa3c0be94ec9842fa023c01f400f4714208ef19289f7d4f8a751918b77082f3d0
-  data.tar.gz: 0d4456c3a1f35e6d8a28e7dbe6b54be40b78dd9ac1919b9b2c919e6294e31f6f0d6c4d24f984873f5df7177ec1cc126794aab6cee59ef31ab76effde706eed9f
+  metadata.gz: d44fd3f4f89ad61d1a75e8393c0cb7f62a104ad4a710584e4c789b189a9a66d6154f23e6a49d3d075c16c7acf81740e18c9a40b86b4a9a046d6176b6c0266639
+  data.tar.gz: 96092e1b5ff5e6fd9cbd5d92a604ae0624ba506a6b0e8f76d9a9465ac819d8e9748c4754481f59160d622716821f795d07fbcd60f0b09530adcb47f3139e8da8

data/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.2.0
+
+### Upgrading from 5.1.1
+
+This release adds tables and columns, so the upgrade is not gem-bump-only.
+From the host app, after bumping the gem:
+
+```sh
+bin/rails spree_bank_payments:install:migrations
+bin/rails db:migrate
+```
+
+`db:migrate` runs the legacy preference migration described under
+"Legacy preference migration" below, which folds your existing `account_*`
+preferences into a `BankAccount` so the store keeps quoting exactly what it
+quoted before. Then read the BREAKING CHANGE below: any host code calling
+`Gateway#bank_details` needs a change.
+
+### BREAKING CHANGE
+
+**`Gateway#bank_details` now returns `Array<Spree::BankPayments::DetailSet>`,
+not a `Hash`.** The method was kept — nothing was renamed or removed — but a
+host reading it as a `Hash` will get a `TypeError`, not a missing-method
+error, the moment it upgrades:
+
+```ruby
+# 5.1.1
+gateway.bank_details[:iban]      #=> "GB00REVO00000000000000"
+
+# 5.2.0
+gateway.bank_details[:iban]      #=> TypeError: no implicit conversion of Symbol into Integer
+gateway.bank_details[0].fields   #=> [["IBAN", "GB00REVO00000000000000"], ["BIC", "REVOGB21"]]
+```
+
+Two alternatives were considered and rejected:
+
+- **Back-mapping the first detail set onto the old five keys** (`:name`,
+  `:iban`, `:bic`, `:sort_code`, `:number`). Rejected: detail-set labels are
+  arbitrary per country (a US account has a routing number, not a sort
+  code), so there is no general mapping back onto five fixed keys. A
+  silently wrong `Hash` — one that quietly drops or mislabels fields — is
+  worse than a loud `TypeError` a host discovers in CI.
+- **Bumping to 6.0.0 instead of 5.2.0.** Rejected: this gem's major version
+  tracks Spree's major version (`spree-bank_payments` 5.x supports Spree
+  5.x). A 6.0.0 release would falsely advertise Spree 6 support that
+  doesn't exist.
+
+**Fix:** call `bank_details_for(currency)` instead, and iterate the returned
+detail sets:
+
+```ruby
+gateway.bank_details_for(order.currency).each do |detail_set|
+  detail_set.label   #=> "UK payments"
+  detail_set.fields   #=> [["Sort code", "04-00-75"], ["Account number", "12345678"]]
+end
+```
+
+`#bank_details` itself is unchanged in one respect: it still quotes the
+*offered* account for the store's default currency (`Spree::Config[:currency]`),
+via `bank_details_for`, and still emits a one-time deprecation warning. Only
+its return type changed, to keep it truthful about what an account now is:
+a store can hold more than one detail set (local + international) per
+currency, and a `Hash` had no way to represent that.
+
+### Added
+
+**Multi-currency bank accounts.** A store can now configure one bank
+account per currency (`Spree::BankPayments::BankAccount`), instead of a
+single flat set of `account_*` preferences shared by every currency. See
+the README's "Bank accounts and currencies" section for the full model —
+briefly:
+
+- Customers are always shown every detail set on the offered account for
+  their order's currency (local and international both) — never inferred
+  from billing country.
+- The admin checklist allows at most one *offered* account per currency,
+  enforced by a partial unique database index — not just a form validation.
+- Every synced account is watched (polled/webhooked) regardless of whether
+  it is offered, so switching which account is offered for a currency never
+  strands a transfer already in flight against the old one.
+- A currency with no offered account is not presented at checkout for that
+  currency (`available_for_order?` returns `false`), unless the order
+  already holds an open same-currency session against this gateway.
+- Accounts can be synced from a provider (`Reconciler#sync_accounts`) or
+  entered by hand in the admin. Sync never sets `offered` and never rewrites
+  `bank_account_id` on an existing session — both are left to a human and to
+  history respectively.
+- A soft-deleted account is not silently resurrected by a later sync; it is
+  reported as skipped in the sync diff instead.
+
+**Legacy preference migration.** A data migration
+(`db/migrate/20260817000004_migrate_legacy_account_preferences.rb`) folds
+any existing `account_*` preferences into one `BankAccount`, marked
+`offered`, for the store's default currency. An upgrading install keeps
+quoting exactly what it quoted before — no manual step required.
+
+### Reconciler contract additions
+
+All additions are backward compatible with the contract published in 5.1.1.
+**A reconciler gem built against 5.1.1 keeps working unmodified against
+5.2.0** — nothing already implemented changed shape, and everything new is
+either optional to override or defaults to `[]`/`nil`.
+
+- **`sync_accounts` → `Array<Spree::BankPayments::AccountData>`.** New,
+  optional override point on `Reconcilers::Base`; the default and `Manual`
+  both return `[]`. `AccountData` carries `provider_account_id`, `currency`,
+  and `details` in the normalised detail-set shape (the same shape
+  `BankAccount#details` stores).
+- **`TransferData` gains `provider_account_id`**, defaulting to `nil`. The
+  initializer is keyword-only, so this is additive: existing construction
+  calls are unaffected.
+- **`poll(since:)` is unchanged.** Per-account fetching stays the
+  provider's business.
+- The exported shared example groups gain a third group,
+  `'a bank transfer reconciler that returns accounts'` — provider authors
+  must run it alongside the existing two (`'a bank transfer reconciler'` and
+  `'a bank transfer reconciler that returns transfers'`) if their reconciler
+  implements `sync_accounts`. It exists because the base group cannot check
+  element types against an empty result.
+
 ## 5.1.1
 
 ### Fixed

data/README.md

@@ -32,7 +32,128 @@ Add a Bank Transfer payment method in the Spree admin and set:
 | `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 |
+| `account_*` | **Deprecated.** Pre-5.2 flat bank details. On upgrade these are folded automatically into one offered `BankAccount` for the store's default currency (see below) — do not set them on a fresh 5.2+ install; use the bank accounts screen instead. |
+
+## Bank accounts and currencies
+
+As of 5.2.0, bank details live on `Spree::BankPayments::BankAccount` rows —
+one per currency you accept, not one flat set of preferences shared by
+every order regardless of currency.
+
+- **One account per currency.** Each account records a `currency` and one
+  or more *detail sets* (a local scheme and an international/SWIFT set are
+  both common). Multiple accounts can exist for the same currency, but at
+  most one can be **offered** at a time — the customer-facing one.
+- **Customers always see every detail set on the offered account** — local
+  and international both, side by side. The gem deliberately does **not**
+  infer which one a customer needs from their billing country: that would
+  require a maintained SEPA-membership list (and it changes), and guessing
+  wrong hides the details the customer actually needed, costing them a
+  bounced transfer or a correspondent fee with no explanation. Let them
+  choose; they know where they bank.
+- **Admin checklist:** the bank accounts screen under the payment method
+  lets an admin toggle at most one *offered* account per currency. This is
+  enforced by a partial unique database index
+  (`index_bp_bank_accounts_on_pm_and_currency_offered`), not just a form
+  validation — a second offered row for the same currency cannot exist,
+  even written directly against the database.
+- **Every synced account stays watched (polled or webhooked) regardless of
+  whether it is offered.** This is what makes switching the offered account
+  safe: quote a customer against GBP account A, later switch the offered
+  GBP account to B — new sessions quote B, but A is still polled, so a
+  transfer that arrives late into A still reconciles automatically against
+  the session it was actually quoted on. No cutover window, no "don't
+  switch until the last order clears."
+- **A currency with no offered account means bank transfer is not
+  available for that currency.** `available_for_order?` returns `false`
+  and the method drops out of checkout for that currency — unless the
+  order already holds an open session against this gateway in the same
+  currency, in which case availability is kept so that order can still be
+  paid. This is easy to reach by accident: **the first sync leaves every
+  account unchecked**, so bank transfer is unavailable in every currency
+  until an admin offers at least one account. The admin screen states this
+  plainly.
+- **Two sync triggers:**
+  1. A **"Sync from <provider>"** button in the payment method admin,
+     which always shows a diff for confirmation before applying it.
+  2. **Consent re-approval**, for providers whose credentials need periodic
+     re-authorisation (e.g. an OAuth consent that expires every ~90 days).
+     A provider gem can call `SyncAccounts.new(payment_method:).apply!(additive_only: true)`
+     from its callback handler; `additive_only` applies new accounts and
+     refreshed details immediately but always skips deactivations, since a
+     currency should never be withdrawn from the storefront mid-redirect
+     with nobody looking at a diff.
+
+  In both cases, **sync never sets `offered`** (that decision stays with a
+  human, including on the very first sync) and **never touches
+  `bank_account_id` on an existing session** — a historical quote is
+  immutable, because changing what a customer was told after the fact
+  makes a dispute unwinnable.
+- **Soft-deleted accounts are not resurrected by sync.** `BankAccount` is
+  `acts_as_paranoid`; deleting one from the admin is a soft delete, so a
+  session that already quoted it keeps rendering the coordinates. If a
+  later sync reports the same provider account again, it is **not**
+  silently recreated — it's surfaced as `skipped` in the sync diff, visible
+  rather than silently reappearing behind an admin's back.
+- **Failed or empty sync leaves every account untouched.** If
+  `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."
+
+### Writing a provider's `sync_accounts`
+
+`sync_accounts` returns `Array<Spree::BankPayments::AccountData>`, each
+carrying `provider_account_id`, `currency`, and `details` in the same
+normalised detail-set shape `BankAccount#details` stores — never the
+provider's raw response shape.
+
+`details` is an ordered list of detail-set **objects**. Each has an optional
+`label`, `schemes`, and `beneficiary_name`, plus `fields`: an ordered list of
+`{ 'label' => …, 'value' => … }` **objects** (not `[label, value]` pairs —
+each field is a hash with a `label` key and a `value` key). Fields are
+label/value rather than named keys because bank coordinates are not
+standardised: a sort code in the UK, a routing number in the US, something
+else again in Poland. The views render them generically, so a market the gem
+has never heard of needs no code change.
+
+```ruby
+def sync_accounts
+  [
+    Spree::BankPayments::AccountData.new(
+      provider_account_id: 'acct_9f2c',
+      currency: 'GBP',
+      details: [
+        {
+          'label' => 'UK payments',
+          'schemes' => ['faster_payments'],
+          'beneficiary_name' => 'Example Store Ltd',
+          'fields' => [
+            { 'label' => 'Sort code',      'value' => '04-00-75' },
+            { 'label' => 'Account number', 'value' => '12345678' }
+          ]
+        },
+        {
+          'label' => 'International',
+          'schemes' => ['swift'],
+          'fields' => [
+            { 'label' => 'IBAN', 'value' => 'GB00REVO00000000000000' },
+            { 'label' => 'BIC',  'value' => 'REVOGB21' }
+          ]
+        }
+      ]
+    )
+  ]
+end
+```
+
+`provider_account_id` must be present and stable — it is the key sync
+reconciles on. A report with a blank id is skipped rather than applied,
+because it cannot be matched to a row without risking overwriting a
+hand-created account. An account whose detail sets contain no usable field
+is skipped too; both appear under `skipped` in the sync diff.
+
+See "Writing a reconciler" below for the full contract, including the shared
+example group that exercises this method's return type.
 
 ## The admin queue and the manual workflow
 
@@ -198,13 +319,18 @@ contract methods:
 - `#healthy?` — boolean; feeds the health gate above
 - `#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>`.
+
 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:
+and run the shared example groups against it — the base group plus
+whichever "returns ..." group(s) apply to your reconciler:
 
 ```ruby
 require 'spree/bank_payments/testing_support/reconciler_shared_examples'
@@ -214,12 +340,15 @@ RSpec.describe MyBank::Reconciler do
 
   it_behaves_like 'a bank transfer reconciler'
   it_behaves_like 'a bank transfer reconciler that returns transfers'
+  it_behaves_like 'a bank transfer reconciler that returns accounts'
 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.
+The "returns ..." groups exist because the base group can't check element
+types: a reconciler with nothing to poll or sync legitimately returns `[]`,
+and any `all(be_a(...))` assertion passes vacuously against an empty array.
+Each "returns ..." group requires the corresponding method to return at
+least one real value and checks its shape — that's the only way to actually
+exercise the type contract. Omit the accounts group if your reconciler
+genuinely can't enumerate accounts (e.g. a manual/no-op reconciler) — forcing
+it there would mean stubbing the class under test, which tests nothing.

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

@@ -0,0 +1,134 @@
+module Spree
+  module Admin
+    class BankAccountsController < Spree::Admin::BaseController
+      before_action :load_payment_method
+      before_action :load_bank_account, only: %i[edit update destroy toggle_offered]
+
+      def index
+        @bank_accounts = @payment_method.bank_accounts.order(:currency, :id)
+      end
+
+      def new
+        @bank_account = @payment_method.bank_accounts.new
+      end
+
+      def create
+        @bank_account = @payment_method.bank_accounts.new(bank_account_params)
+
+        if @bank_account.save
+          redirect_to_index 'Bank account created.'
+        else
+          render :new
+        end
+      rescue JSON::ParserError
+        @bank_account = @payment_method.bank_accounts.new(raw_bank_account_params.except(:details))
+        @bank_account.errors.add(:details, 'must contain valid JSON')
+        render :new
+      end
+
+      def edit; end
+
+      def update
+        # Synced accounts are the provider's record, not ours -- editing their
+        # currency or details here would silently diverge from the account
+        # actually watched. Checked against the *raw*, unparsed params so a
+        # malformed `details` payload can't slip past this guard by raising
+        # JSON::ParserError before it runs (see the JSON.parse call in
+        # #bank_account_params).
+        if @bank_account.synced? && synced_field_present?
+          flash[:error] = 'Synced accounts cannot be edited. Re-sync to refresh them.'
+          return redirect_to_index
+        end
+
+        if @bank_account.update(bank_account_params)
+          redirect_to_index 'Bank account updated.'
+        else
+          render :edit
+        end
+      rescue JSON::ParserError
+        @bank_account.errors.add(:details, 'must contain valid JSON')
+        render :edit
+      end
+
+      def destroy
+        if @bank_account.synced?
+          flash[:error] = 'Synced accounts cannot be deleted. Deactivate instead.'
+        else
+          @bank_account.destroy
+        end
+
+        redirect_to_index
+      end
+
+      def toggle_offered
+        Spree::BankPayments::BankAccount.transaction do
+          @payment_method.bank_accounts.
+            for_currency(@bank_account.currency).offered.
+            where.not(id: @bank_account.id).
+            update_all(offered: false)
+
+          @bank_account.update!(offered: !@bank_account.offered?)
+        end
+
+        redirect_to_index
+      end
+
+      # Never builds and holds a plan across the request: `apply!` with no
+      # argument derives and validates the plan itself, including the abort
+      # guard against a provider auth failure returning `[]` (which `plan`
+      # would otherwise read as "every account disappeared" and deactivate
+      # all of them). Passing a pre-built plan here would bypass that guard
+      # entirely -- see SyncAccounts#apply! and #plan.
+      #
+      # Rescues only EmptyResponseError -- the one operational failure
+      # SyncAccounts itself distinguishes from a programming error. A bare
+      # `rescue StandardError` here would also swallow a NoMethodError or
+      # similar bug and report it to the admin as an unremarkable "Sync
+      # failed", hiding it instead of surfacing it as the 500 it should be.
+      def sync
+        Spree::BankPayments::SyncAccounts.new(payment_method: @payment_method).apply!
+        redirect_to_index 'Accounts synced.'
+      rescue Spree::BankPayments::SyncAccounts::EmptyResponseError => e
+        flash[:error] = "Sync failed: #{e.message}. No accounts were changed."
+        redirect_to_index
+      end
+
+      private
+
+      def load_payment_method
+        @payment_method = Spree::BankPayments::Gateway.find(params[:payment_method_id])
+      end
+
+      def load_bank_account
+        @bank_account = @payment_method.bank_accounts.find(params[:id])
+      end
+
+      def redirect_to_index(notice = nil)
+        flash[:success] = notice if notice
+        redirect_to spree.admin_payment_method_bank_accounts_path(@payment_method)
+      end
+
+      # `active` is deliberately NOT permitted. It is sync's field, not the
+      # admin's: it records whether the provider still reports the account,
+      # and the form offers no control for it. Permitting it meant a
+      # hand-crafted PUT could set `active: false` on the offered account,
+      # which withdraws that currency from checkout entirely
+      # (Gateway#offered_account_for scopes by `active`) until the next sync
+      # flips it back. The admin's lever is `offered` (toggle_offered).
+      def raw_bank_account_params
+        params.require(:bank_account).permit(:currency, :offered, :details)
+      end
+
+      def synced_field_present?
+        raw = raw_bank_account_params
+        raw.key?(:currency) || raw.key?(:details)
+      end
+
+      def bank_account_params
+        permitted = raw_bank_account_params
+        permitted[:details] = JSON.parse(permitted[:details]) if permitted[:details].is_a?(String)
+        permitted
+      end
+    end
+  end
+end

data/app/mailers/spree/bank_payments/instructions_mailer.rb

@@ -4,7 +4,7 @@ module Spree
       def instructions(payment_session_id)
         @session = ::Spree::PaymentSessions::BankTransfer.find(payment_session_id)
         @order = @session.order
-        @bank_details = @session.payment_method.bank_details
+        @detail_sets = @session.bank_detail_sets
 
         with_store_locale(@order.store) do
           mail(to: @order.email, subject: Spree.t('bank_payments.reference'))
@@ -14,7 +14,7 @@ module Spree
       def reminder(payment_session_id)
         @session = ::Spree::PaymentSessions::BankTransfer.find(payment_session_id)
         @order = @session.order
-        @bank_details = @session.payment_method.bank_details
+        @detail_sets = @session.bank_detail_sets
         @days_remaining = ((@session.expires_at.to_date - Date.current).to_i)
 
         with_store_locale(@order.store) do

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

@@ -0,0 +1,12 @@
+module Spree
+  module BankPayments
+    # 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)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+module Spree
+  module BankPayments
+    # One account money can arrive in. `offered` decides whether customers are
+    # quoted it; every active account is watched regardless, which is what makes
+    # switching accounts safe for orders already in flight.
+    class BankAccount < Base
+      # Spree::PaymentMethod (our belongs_to parent) is acts_as_paranoid.
+      # Without this, Gateway's `dependent: :destroy` on #bank_accounts would
+      # hard-delete these rows the moment an admin soft-deletes the gateway --
+      # restoring the gateway a day later would not bring the coordinates
+      # back. Spree::PaymentSession is paranoid for the same reason.
+      acts_as_paranoid
+
+      belongs_to :payment_method, class_name: 'Spree::PaymentMethod'
+
+      validates :currency, presence: true, format: { with: /\A[A-Za-z]{3}\z/ }
+      # Mirrors index_bp_bank_accounts_on_pm_and_currency_offered exactly
+      # (payment_method_id + currency, where offered AND deleted_at IS NULL --
+      # acts_as_paranoid's default scope already excludes soft-deleted rows
+      # from this uniqueness check). The database index is the real
+      # guarantee; this validation exists only so an admin offering a second
+      # account for a currency they already offer sees a form error instead
+      # of an unrescued RecordNotUnique.
+      validates :currency,
+                uniqueness: { scope: :payment_method_id, conditions: -> { where(offered: true) },
+                              message: 'already has an offered account for this currency' },
+                if: :offered?
+      validate :details_is_a_list_of_objects
+      validate :has_a_usable_detail_set
+
+      scope :offered, -> { where(offered: true) }
+      scope :active,  -> { where(active: true) }
+      scope :for_currency, ->(code) { where(currency: code.to_s.upcase) }
+
+      before_validation :normalize_currency
+
+      # @return [Array<Spree::BankPayments::DetailSet>] one per *object* entry.
+      #   Non-object entries are skipped rather than raising: `details` is
+      #   admin-editable JSON, and `Array(a_hash)` yields `[[key, value]]`, so
+      #   an admin pasting `{"label": ...}` where an array belongs used to blow
+      #   up with NoMethodError inside a validation. #details_is_a_list_of_objects
+      #   turns that into a form error instead.
+      def detail_sets
+        Array(details).grep(Hash).map { |raw| DetailSet.new(raw) }
+      end
+
+      def synced?
+        provider_account_id.present?
+      end
+
+      private
+
+      def normalize_currency
+        self.currency = currency.to_s.upcase.presence
+      end
+
+      # `details` is a JSON array of detail-set objects. Anything else is a
+      # form error, not an exception: the admin form takes raw JSON, so a
+      # pasted object (`{"label": ...}`) or a bare scalar is an ordinary typo.
+      def details_is_a_list_of_objects
+        return if details.nil?
+        return if details.is_a?(Array) && details.all?(Hash)
+
+        errors.add(:details, 'must be a JSON array of detail set objects')
+      end
+
+      # An account with no payable coordinates is worse than no account: the
+      # customer is quoted an empty instruction block and has nowhere to send
+      # money.
+      def has_a_usable_detail_set
+        # Shape already reported; a second error about the same field only
+        # obscures the actual problem.
+        return if errors.key?(:details)
+        return if detail_sets.any?(&:usable?)
+
+        errors.add(:details, :blank)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Spree
+  module BankPayments
+    # One set of payable coordinates for an account -- a local scheme, or SWIFT.
+    #
+    # `fields` is an ordered list of label/value pairs rather than named keys
+    # because bank coordinates are not standardised: the UK uses a sort code and
+    # account number, the US a routing number, Poland's Elixir something else
+    # again. Named columns or fixed keys would mean a migration per market.
+    class DetailSet
+      # @param raw [Hash] anything that is not a Hash is treated as an empty
+      #   detail set rather than raising. `details` is admin-editable JSON and
+      #   provider-supplied data, so the shape is not guaranteed: a JSON object
+      #   pasted where an array belongs arrives here as an `[key, value]` pair,
+      #   and a provider following the README's old (wrong) `[[label, value]]`
+      #   field shape arrives as an Array too. Both used to raise NoMethodError
+      #   deep inside a validation or mid-sync. Unusable input must surface as
+      #   a form error or a skipped account, never a 500.
+      def initialize(raw)
+        @raw = raw.is_a?(Hash) ? raw.transform_keys(&:to_s) : {}
+      end
+
+      def label
+        @raw['label'].presence
+      end
+
+      def schemes
+        Array(@raw['schemes']).map(&:to_s)
+      end
+
+      def beneficiary_name
+        @raw['beneficiary_name'].presence
+      end
+
+      def beneficiary_address
+        @raw['beneficiary_address']
+      end
+
+      # @return [Array<Array(String, String)>] ordered [label, value] pairs
+      def fields
+        # grep(Hash): a field entry that is not an object (e.g. the
+        # `[label, value]` pair the README wrongly documented until 5.2.0) is
+        # dropped, not raised on. An account whose every field is dropped is
+        # simply not `usable?`.
+        Array(@raw['fields']).grep(Hash).filter_map do |field|
+          f = field.transform_keys(&:to_s)
+          value = f['value'].to_s.strip
+          next if value.empty?
+
+          [f['label'].to_s, value]
+        end
+      end
+
+      def usable?
+        fields.any?
+      end
+
+      def to_h
+        @raw
+      end
+    end
+  end
+end