Partial Refunds

Stripe supports partial refunds via the Stripe Dashboard. I think other processors support similar.

To record a partial refund in CiviCRM we can record a negative payment on the contribution using API Payment.create.

Currently nothing changes on the contribution:

• Total amount still shows the full amount but payments are recorded correctly so the sum of payments does not equal the contribution total amount.
• Contribution status remains Completed.

What should happen(?):

• A partial refund means that the total_amount paid, tax_amount and the fee_amount paid may be reduced.
• The contribution status is no longer "Completed" and should be Partially refunded (does not exist)? Partially paid (already exists).
• The Financial Type should be displayed correctly for the refund payment.

Currently, viewing a contribution, either in the summary or detail gives no indication of the actual amount paid:

@JoeMurray @eileen @artfulrobot @ayduns Thoughts please?

This also applies in the other direction - if we make an overpayment you can't see that from the contribution summary.

added sig:bug sig:payment labels

@mattwire so my expectation is that the Payment.create api will not change the contribution total - ie we have an order, we pay too much for it - it doesn't change the value of the order it just means we've overpaid (& are probably due a credit). Ideally if you want to change the Order you would use the order api (hopefully it works for that but likely has gaps) or the line item editor.

I agree the status contribution should change. I'm not sure what to.

There is something a bit odd with 'Partially refunded' it implies that a refund became due and was issued in part. In fact you could get a scenario where

1. I order a cart of events
2. I pay with a card payment & some cash. The payment is added. It changes to 'Completed'
3. I come back & say 'OMG please give me the cash back, I'll pay the rest by card'
4. A refund of the cash payment is added - at this point the right status IMHO is 'Partially Paid' because the finally goal is still to Pay it & for it to be completed.

'Partially refunded' makes sense to me when I cancel the event & it's now 'pending refund' & my cash is returned to me - it's partially refunded because the end goal is 'refunded' (although sometimes partially refunded IS the end goal - sigh).

Maybe we should have an 'overpaid' status?

@JoeMurray

Although "Currently, viewing a contribution, either in the summary or detail gives no indication of the actual amount paid:" - yes we should show the total paid

added needs:concept approval triaged labels

added type:proposal label and removed sig:bug label

Rather than another status - which I know causes @JoeMurray nightmares :-) I think leave it completed but update the UI - perhaps the UI could have something that shows up if the total contribution != the total paid?

mentioned in issue #103

changed the description

mentioned in issue core#1574 (closed)

We at AGH are in the process of building out the TSYS payment processor integration to issue partial refunds. I am trying to get up to speed on the latest core plans...ideas...schemes... etc. for refunding (this seems to be one of the more recent tickets regarding refunds).

We have been working towards a UI where when viewing a contribution each payment that is eligible to be refunded in TSYS includes a "refund" link next to the edit pencil like in the screenshot below:

(hence https://github.com/civicrm/civicrm-core/pull/16401 which makes it possible to add actions to the Payment action links).

When one clicks the refund button they are taken to a form where they can enter the amount to be refunded (the full amount or part of it). On submit of that form the refund is processed in TSYS and the 'Payment.create' api is called using a negative amount to record the refund in CiviCRM. Mostly this is working but we have run into some hurdles like not being able to update a "Completed" contribution status to "Partially Paid" when only refunding part of the contribution which it looks like was discussed in #103 and some other inconsistencies in how the api functions when recording/cancelling/refunding payments (which I will document in a related issue).

Mostly I am commenting to say we would love to help move the ball forward on improving the partial refund workflow.

@alicefrumin Great :-) Did you find the same issue as above where "The Financial Type should be displayed correctly for the refund payment." If you are able to work out why that is happening and do a core PR that would be awesome and I'll certainly put the time in to review.

Moving this forward (and #103) requires lot's of little changes and some agreement about how things should work along the way. And some time :-)

Also note that a full refund was recently fixed so the contribution changes to "Refunded": https://github.com/civicrm/civicrm-core/pull/16148

Yes! I did run into the issue where "The Financial Type should be displayed correctly for the refund payment." I can look into that next week.

Per this PR - https://github.com/civicrm/civicrm-core/pull/16480 I think we should clean up the additional payment form & then it should be fairly easy to extend

Note the financial type will display if the refund is allocated to line items (via financial item) - we did add docs on that

I did some digging on the financial type not showing up for refunds created using Payment.create. I think it boils down to Payment.create not creating a financial item as Eileen suggests. It looks to me like this is intentional based on this issue https://github.com/civicrm/civicrm-core/pull/15143.

More details below:

It looks to me like the Payment Info displayed in the Payment Details table is pulled using this query, name being the financial type, it pulls the Financial Type from the related Financial Item (connected by an civicrm_entity_financial_trxn entry). However, there is no financial_item created when a refund is created using Payment.create, just a financial_transaction (this is discussed here: https://github.com/civicrm/civicrm-core/pull/15143).

Perhaps this is the documentation Eileen is referring to: https://docs.civicrm.org/dev/en/latest/financial/financialentities/

Yep - that looks about right

I note this comment in there "!! this same should happen for a negative payment although the allocation may be different. There may be a current bug here." - if you think it's wrong then I'd start with a PR to the docs page proposing how it 'should' be

Good Suggestion Eileen, I will work towards that. I'm going to spend some time playing around with it to be sure I fully understand how it works.

mentioned in commit core@4356c7dc

mentioned in commit core@879ff7b8

mentioned in issue extensions/stripe#260 (closed)

mentioned in issue #186

Just to add a link to a more detailed analysis of the situation here that might be of interest to some: #186

The "Payment Shared" refund UI now supports partial refunds: https://docs.civicrm.org/mjwshared/en/latest/refunds/

Note that The contribution status is no longer "Completed" and should be Partially refunded (does not exist)? Partially paid (already exists).

is not working in CiviCRM core and probably still needs looking into.