Implement a payment capture events GUI

[tvdeyen]

Following these discussions

• Spree PR
• Spree commit introducing capture events
• Slack discussion

we are missing an interface for capturing partial payments (Spree::PaymentCaptureEvent)

So, @moritzps, @pascalj and @rbjoern84 from @bitspire started a discussion on Slack about implementing one.

This is the original screenshot of the UI they proposing

TODO

• Display the form above/below the payment capture events table
• Display the form under the payment details if no capture events are present yet
• Prefill remaining amount in the field (payment amount minus sum of all captured events)
• Do not display form if no money can be captured anymore (the full amount of the payment is reached)

[tvdeyen]

One thing I discussed with @pascalj IRL was to add a form for capturing partial payments to the payments detail page. Introducing a modal (we did not finally decided to have in our UI now) for this rarely used feature seems overkill for us.

Payment Detail page with capture events

We need to keep in mind that payments could be uncaptured and therefor do not have an Spree::PaymentCaptureEvent yet. But we still have the payments detail page, so we could still display the form and pre-fill the amount into the field

Payment Detail page without capture events

The form should not be displayed if no money can be captured anymore (aka. the full amount of the payment is reached)

[pascalj]

After going through some commits and reading the comment at processing.rb I thought everything was in place for partial captures. Unfortunately the feature was removed shortly after it was introduced, rendering the comment outdated/wrong.

I cannot find a belonging PR, but I guess this stems from the difference between:

• partial payments (multiple captures for one payment)
• payments with a lower captured amount than the authorized amount (e.g. after editing on the payment index page)

I'd gladly add a new method to the controller to get around that, but the transition to completed is done in the payment (Processing#capture!) itself. After a payment is completed there cannot be any more captures.

Adjusting the capture method even more with unknown side effects will probably be reverted again in the future, just as before. So I'd like to add a partial_capture! method which emits a capture event and leaves the payment in its current state until fully captured. Another option would be to split the payment as before. Any thoughts/preferences on that?

[pascalj]

I'd like to get some feedback on the general behaviour of capturing. For some code that allows partial capturing see #2039.

• I tried to not introduce a new method in processing and use the already available capture! method. The problem is that it has different semantics than I expected: it will capture the amount specified as an argument and reduce the overall amount of the payment and transition to completed. I think this was done for cases when an order is auto-captured and the remaining sum to pay is smaller than what was authorized. That way payments will always end up in complete, even if only a part is captured.
• This is reflected in the two failing specs:
  • /spec/models/spree/payment_spec.rb:454 "Spree::Payment processing #capture! when payment is pending capturing a partial amount updates the amount of the payment"
  • ./spec/lib/tasks/order_capturing_spec.rb:26 "order_capturing:capture_payments with a mix of canceled and shipped inventory charges the order"

What option do you prefer?

1. Add a new method inside of the payment processing a la partial_capture!(amount)?
2. Don't change the amount any more (kind of what [WIP] partial captures #2039 does) and change the specs in that regard. Could be a braking change, but it's definitely an edge case.
3. "Force" payments to completed after their order was completed, no matter what their respective uncaptured_amount is.
4. None of the above, but <thing>?

Any feedback is welcome!

[tvdeyen]

We will discuss this in the next core team meeting. Thanks for the write up

[jhawthorn]

Is there a popular gateway which supports multiple captures? Certainly they all support partial captures, but I don't know of any which support multiple captures (other than by making multiple charges against a stored credit card)

[pascalj]

Absolutely, it's not that common. Examples are Paypal and Amazon Pay which both work with only one authorization.

This amount cannot exceed the original amount that was authorized less any previously captured amount on this authorization

[pascalj]

Copying @cbrunsdon's response from #2039 so it's all in one place:

I definitely think the change is a good direction (multiple captures when payment gateways support it), but I'm worried that this is going to be a big change that everyone will get, even when multiple capture is not supported by payment gateways.

I do however think this is a very reasonable, and not too intrusive for an extension, would you consider supporting it in that way? If it lives there for a while and the kinks get worked out, I would be happy to re-examine it for core in a future release.

Yes, I can see why touching that part of Solidus could cause problems, especially for third party code. I'll try to ship it as an extension - this would potentially allow to use it with older Solidus versions, too. Without overriding anything it'll:

• add a small controller to handle the partial_capture without changing the payment's amount
• add the form to the payment page
• maybe add a callback to the order updater to complete the payments once an order is complete

Thanks for all your feedback!