Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Add missing flow which handles retryable transfers

Kacper Mekarski57e44f1fcb62
diff --git a/spree/core/app/jobs/spree/seller_transfers/execute_pending_due_job.rb b/spree/core/app/jobs/spree/seller_transfers/execute_pending_due_job.rb
new file mode 100644
index 0000000000..cf6ba0449d
--- /dev/null
+++ b/spree/core/app/jobs/spree/seller_transfers/execute_pending_due_job.rb
@@ -0,0 +1,56 @@
+module Spree
+ module SellerTransfers
+ # Hands every seller holding an unconfirmed earning to a job of their own.
+ #
+ # The transfer level's counterpart to {Spree::SellerPayouts::SweepDueJob},
+ # and deliberately a separate schedule rather than something the settlement
+ # run does on its way past. The two answer different questions on different
+ # clocks: a settlement waits for the seller's own interval, which a
+ # marketplace measures in weeks, while an earning the provider refused is
+ # owed *now* and the refusal is usually a passing thing — a platform
+ # balance that has not settled, a rate limit, a charge not yet usable as a
+ # funding source. Run this hourly and that earning clears within the hour;
+ # tie it to the settlement run and it waits for the next one.
+ #
+ # Only sellers who actually have something outstanding are enqueued. The
+ # awaiting set is the exception rather than the rule, so on a healthy
+ # marketplace this fans out to nobody.
+ #
+ # Scheduled by the host app, like every other recurring job in core.
+ class ExecutePendingDueJob < ::Spree::BaseJob
+ queue_as Spree.queues.payouts
+
+ # How many jobs are handed to the adapter at a time, matching the
+ # settlement enumerator.
+ BATCH_SIZE = 1_000
+
+ def perform
+ # Store by store, so each seller is reached through the store that owns
+ # them and the provider question below is asked of the right one.
+ Spree::Store.find_each do |store|
+ sellers_awaiting_provider(store).in_batches(of: BATCH_SIZE) do |sellers|
+ ActiveJob.perform_all_later(sellers.ids.map { |id| ExecutePendingJob.new(id) })
+ end
+ end
+ end
+
+ private
+
+ # @param store [Spree::Store]
+ # @return [ActiveRecord::Relation<Spree::Seller>]
+ def sellers_awaiting_provider(store)
+ scope = store.sellers.approved.
+ where(id: Spree::SellerTransfer.for_store(store).awaiting_provider.select(:seller_id))
+
+ # A seller the provider will not accept yet keeps their earnings
+ # unconfirmed, and the job would return at once. Skipped rather than
+ # enqueued, because a marketplace's half-onboarded sellers are a
+ # standing population and this runs often — and nothing is lost by it:
+ # finishing onboarding runs the job for them directly.
+ return scope unless store.payout_provider_class.requires_payout_account?
+
+ scope.where.not(payouts_enabled_at: nil)
+ end
+ end
+ end
+end
diff --git a/spree/core/app/jobs/spree/seller_transfers/execute_pending_job.rb b/spree/core/app/jobs/spree/seller_transfers/execute_pending_job.rb
index ddb08cdd67..696d53a25c 100644
--- a/spree/core/app/jobs/spree/seller_transfers/execute_pending_job.rb
+++ b/spree/core/app/jobs/spree/seller_transfers/execute_pending_job.rb
@@ -4,12 +4,15 @@ module Spree
#
# A seller who ships while their payout account is still being verified has
# earned all the same, so the ledger records the row and leaves it pending.
- # What clears it is this job, run when the seller becomes payable — the
- # event that changed, rather than the next scheduled settlement.
+ # So does a seller whose provider simply refused the call. Either way the
+ # money is owed, and no settlement will find it: a sweep collects confirmed
+ # earnings, and these are not confirmed.
#
- # That distinction matters: a sweep would never reach these rows, because
- # it looks for confirmed earnings and a seller whose only rows are pending
- # has none, so nothing would prompt it in the one case this exists for.
+ # Two callers, for the two ways a row gets here. A seller becoming payable
+ # runs it at once, because that is the moment the answer changed. Everyone
+ # else is reached by {ExecutePendingDueJob} on a schedule — without it, a
+ # seller who was payable all along would never see a refused earning tried
+ # again, since nothing about them ever changes to prompt it.
#
# It takes the retryable rows — never sent, or refused outright. A transfer
# whose outcome the provider could not report is left alone: asking again
@@ -25,11 +28,11 @@ module Spree
provider = seller.store.payout_provider_instance
- # Earnings only. A reversal is retryable the same way when its own
- # provider call is refused, but sending one through `transfer!` would
- # pay the seller the amount it exists to take back — the row is
- # negative and the amount sent is its absolute value.
- seller.seller_transfers.earnings.retryable.where(payout_id: nil).find_each do |transfer|
+ # Earnings only — see the scope. A reversal is retryable the same way
+ # when its own provider call is refused, but sending one through
+ # `transfer!` would pay the seller the amount it exists to take back:
+ # the row is negative and the amount sent is its absolute value.
+ seller.seller_transfers.awaiting_provider.find_each do |transfer|
provider.transfer!(transfer)
rescue Spree::Core::AmbiguousGatewayError => e
# The money may already have moved, so this row must not be offered
diff --git a/spree/core/app/models/spree/seller_transfer.rb b/spree/core/app/models/spree/seller_transfer.rb
index 0f593068cf..dc3c53dc09 100644
--- a/spree/core/app/models/spree/seller_transfer.rb
+++ b/spree/core/app/models/spree/seller_transfer.rb
@@ -73,6 +73,11 @@ module Spree
# Deliberately excludes `unresolved`, where the provider could not say
# whether the money moved — asking again is how it moves twice.
scope :retryable, -> { with_status('pending', 'processing') }
+ # Earnings still owing the provider a call.
+ # Reversals are excluded for the same reason the job excludes them: their
+ # amount is negative, and sending one as a transfer pays the seller the
+ # money it exists to take back.
+ scope :awaiting_provider, -> { earnings.retryable.where(payout_id: nil) }
# Earned and confirmed, but not yet swept into a settlement — what the next
# payout will pick up.
scope :unsettled, -> { completed.where(payout_id: nil) }
diff --git a/spree/core/app/workflows/spree/seller_transfers/create.rb b/spree/core/app/workflows/spree/seller_transfers/create.rb
index 42f7401916..469b16b7ba 100644
--- a/spree/core/app/workflows/spree/seller_transfers/create.rb
+++ b/spree/core/app/workflows/spree/seller_transfers/create.rb
@@ -73,7 +73,8 @@ module Spree
# A seller the provider cannot pay yet keeps the earning as a pending
# row. Verification can take days, and an account can lose the
# capability again — either way the money is owed, and
- # `SellerTransfers::ExecutePendingJob` sends it once they are payable.
+ # `SellerTransfers::ExecutePendingJob` sends it once they are payable,
+ # or on its next scheduled run if that moment went unseen.
return unless order.seller.payouts_enabled?
provider.transfer!(seller_transfer)
diff --git a/spree/core/spec/jobs/spree/seller_payouts/sweep_seller_job_spec.rb b/spree/core/spec/jobs/spree/seller_payouts/sweep_seller_job_spec.rb
index e9a17ce774..fbff576d91 100644
--- a/spree/core/spec/jobs/spree/seller_payouts/sweep_seller_job_spec.rb
+++ b/spree/core/spec/jobs/spree/seller_payouts/sweep_seller_job_spec.rb
@@ -58,4 +58,14 @@ RSpec.describe Spree::SellerPayouts::SweepSellerJob do
it 'does nothing for a seller that has gone' do
expect { described_class.perform_now(-1) }.not_to raise_error
end
+
+ # Confirming an earning is the transfer level's business, on its own
+ # schedule — see Spree::SellerTransfers::ExecutePendingDueJob.
+ it 'leaves an unconfirmed earning to the job that owns it' do
+ create(:seller_transfer, seller: seller, amount: 40, status: 'processing',
+ order: create(:order, store: store, seller: seller))
+
+ expect { described_class.perform_now(seller.id) }.
+ not_to have_enqueued_job(Spree::SellerTransfers::ExecutePendingJob)
+ end
end
diff --git a/spree/core/spec/jobs/spree/seller_transfers/execute_pending_due_job_spec.rb b/spree/core/spec/jobs/spree/seller_transfers/execute_pending_due_job_spec.rb
new file mode 100644
index 0000000000..0e55afff00
--- /dev/null
+++ b/spree/core/spec/jobs/spree/seller_transfers/execute_pending_due_job_spec.rb
@@ -0,0 +1,121 @@
+require 'spec_helper'
+
+RSpec.describe Spree::SellerTransfers::ExecutePendingDueJob do
+ let(:store) { @default_store }
+ let(:seller) { create(:seller, :approved, store: store) }
+
+ def enqueued_seller_ids
+ enqueued_jobs.
+ select { |job| job[:job] == Spree::SellerTransfers::ExecutePendingJob }.
+ map { |job| job[:args].first }
+ end
+
+ def earning(status:, owner: nil)
+ owner ||= seller
+ create(:seller_transfer, seller: owner, amount: 40, status: status,
+ order: create(:order, store: owner.store, seller: owner))
+ end
+
+ # An earning the provider never accepted is counted in no balance and
+ # collected by no settlement, and the hooks that retry one fire when a seller
+ # *becomes* payable — which never happens again for a seller who was payable
+ # all along. This job is the only thing that revisits them.
+ it 'hands a seller with a refused earning to a job of their own' do
+ earning(status: 'processing')
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to contain_exactly(seller.id)
+ end
+
+ it 'hands over one whose earning was never sent at all' do
+ earning(status: 'pending')
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to contain_exactly(seller.id)
+ end
+
+ # Confirming an earning is not settling it, so the seller's settlement
+ # schedule has no bearing here: an operator paying by hand still has to see
+ # what they owe.
+ it 'hands over a seller the marketplace settles by hand' do
+ seller.update!(payouts_schedule_interval: 'manual')
+ earning(status: 'processing')
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to contain_exactly(seller.id)
+ end
+
+ # Asking again is how the same money moves twice.
+ it 'leaves an earning nobody can account for alone' do
+ earning(status: 'unresolved')
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to be_empty
+ end
+
+ it 'says nothing when every earning is confirmed' do
+ earning(status: 'completed')
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to be_empty
+ end
+
+ # A settlement has already claimed it, so it is not the provider that is
+ # owed a call.
+ it 'ignores an earning a settlement holds' do
+ earning(status: 'pending').update!(payout: create(:seller_payout, seller: seller))
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to be_empty
+ end
+
+ it 'ignores a seller who is not approved' do
+ pending_seller = create(:seller, store: store, status: 'pending')
+ earning(status: 'processing', owner: pending_seller)
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to be_empty
+ end
+
+ it 'reaches sellers across every store' do
+ earning(status: 'processing')
+ other_seller = create(:seller, :approved, store: create(:store))
+ earning(status: 'processing', owner: other_seller)
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to contain_exactly(seller.id, other_seller.id)
+ end
+
+ # The job would return at once, and a marketplace's half-onboarded sellers
+ # are a standing population against a job that runs often. Nothing is lost:
+ # finishing onboarding runs the job for them directly.
+ context 'when the provider will not accept the seller yet' do
+ before { allow(Spree::PayoutProvider::System).to receive(:requires_payout_account?).and_return(true) }
+
+ it 'passes over them' do
+ seller.update!(payouts_enabled_at: nil)
+ earning(status: 'processing')
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to be_empty
+ end
+
+ it 'hands over one the provider has since accepted' do
+ seller.update!(payouts_enabled_at: Time.current)
+ earning(status: 'processing')
+
+ described_class.perform_now
+
+ expect(enqueued_seller_ids).to contain_exactly(seller.id)
+ end
+ end
+end