Skip to content

Prevent refunds from exceeding a payment's amount - #6737

Merged
AlistairNorman merged 1 commit into
solidusio:mainfrom
VickTor61:VickTor61/refunds-exceed-payment-amount
Nov 19, 2026
Merged

AlistairNorman merged 1 commit into
solidusio:mainfrom
VickTor61:VickTor61/refunds-exceed-payment-amount

Conversation

@VickTor61

Copy link
Copy Markdown
Contributor

Summary

Fixes #6708

A payment could end up with more refunded than its amount. Solidus allows refunds on pending (authorized but not yet captured) payments, and the refund is only checked against credit_allowed when it is created. A later partial capture!, or an update to the payment's amount, could then lower the amount below what was already refunded. For example:

  1. Authorize a $6.00 payment (pending).
  2. Refund $6.00. This is valid, since credit_allowed is 6.00.
  3. capture!(200) captures $2.00 and sets amount to 2.00.

The result is credit_allowed == -4.00 and an order payment_total of -4.00 (outstanding balance 10.00 on a 6.00 order).

This PR makes "refunds never exceed the payment's amount" hold:

  • Spree::Payment validation: a persisted payment's amount can't be less than the sum of its refunds. This covers amount updates from the API, the admin, or custom code.
  • Guard in capture!: a capture for less than the refunded amount is refused with a Spree::Core::GatewayError, before the gateway is called. A validation alone wouldn't be enough here. capture! runs update!(amount: captured_amount) after payment_method.capture, so it would fail only after the money had already been captured.

Both error messages are localized in core/config/locales/en.yml.

Notes for reviewers

  • I chose to raise in capture! rather than return false, so the reason is visible to whoever triggered the capture. Happy to change it if returning false is preferred.
  • The related issue mentioned in Refunds can exceed a payment's amount after a partial capture! #6708 is intentionally left out of this PR to keep it focused. capture! records the capture event and updates amount before handle_response, so a capture the gateway rejects still records a captured amount. I can follow up separately.

Tests

New specs in core/spec/models/spree/payment_spec.rb:

  • a partial capture smaller than the refunds is refused, the gateway isn't called, and no capture event is logged;
  • a capture that covers the refunds still completes;
  • an amount below the refunds total is invalid, and an amount equal to it is still valid.

The "refused" and "invalid" specs fail without this change and pass with it. The core payment specs, the API payment request specs, and the backend admin payments and refunds controller specs pass locally.

Checklist

Check out our PR guidelines for more details.

The following are mandatory for all PRs:

The following are not always needed:

  • 📖 I have updated the README to account for my changes.
  • 📑 I have documented new code with YARD.
  • 🛣️ I have opened a PR to update the guides.
  • ✅ I have added automated tests to cover my changes.
  • 📸 I have attached screenshots to demo visual changes.

🤖 Generated with Claude Code

@VickTor61
VickTor61 requested a review from a team as a code owner November 17, 2026 16:59
@github-actions github-actions Bot added the changelog:solidus_core Changes to the solidus_core gem label Nov 17, 2026
@codecov

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.68%. Comparing base (f11cf71) to head (d9c756d).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #6737   +/-   ##
=======================================
  Coverage   92.68%   92.68%           
=======================================
  Files        1082     1082           
  Lines       22007    22018   +11     
=======================================
+ Hits        20397    20408   +11     
  Misses       1610     1610           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment thread core/app/models/spree/payment.rb Outdated
validates :amount, numericality: true
validates :source, presence: true, if: :source_required?
validates :payment_method, presence: true
validate :amount_not_less_than_refunds, if: :persisted?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will break existing invalid payments, making it impossible to update them. What about :will_save_change_to_amount? as the condition?

@VickTor61 VickTor61 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I switched the condition to will_save_change_to_amount?. Thanks for catching that bug

A pending payment can be refunded, and a later partial `capture!` (or an
amount update) would then lower its amount below what was refunded,
leaving `credit_allowed` and the order's `payment_total` negative.

- Validate that a payment's amount is not less than the sum of its
  refunds. The check only runs when the amount is changing, so payments
  that already have more refunded than their amount (created before
  this fix) can still be updated.
- Refuse a `capture!` for less than the refunded amount before calling
  the gateway, so no money is captured for a payment we would reject.

Fixes solidusio#6708

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@VickTor61
VickTor61 force-pushed the VickTor61/refunds-exceed-payment-amount branch from 1876165 to d9c756d Compare November 18, 2026 06:25
@AlistairNorman
AlistairNorman merged commit c01bf0a into solidusio:main Nov 19, 2026
43 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog:solidus_core Changes to the solidus_core gem

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Refunds can exceed a payment's amount after a partial capture!

3 participants