Handling partial reversals

Full reversals are boring and well-covered. Partial reversals — reversing part of an authorization, capturing part of it, refunding part of a capture — are where the integration assumptions leak.

Written December 2025 from a set of partial-reversal debugging sessions.

Why partial reversals are harder

• The original authorization has a full amount. A partial reversal has to reference both the original and the amount being reversed.
• Repeated partial actions. Multiple partial captures against one authorization; multiple partial refunds against one capture. Every one of them creates a new event with its own state.
• Currency conversion. Partial actions in a currency different from the original raise conversion-timing questions.
• Scheme-specific rules. Not every scheme supports partial reversal identically. Some allow multiple partial captures; some don't. Some allow overrefund; some don't.

Design patterns that work

• Every partial action gets its own event, linked to the parent. The parent's remaining balance is derived, not stored — it's the parent amount minus the sum of children.
• The merchant view shows the parent with children. A merchant looking at a transaction sees the full history: original authorization, first partial capture, second partial capture, refund on the second.
• Reconciliation is per-event, not per-parent. Each partial action reconciles independently; the parent's state is derived from the reconciliation of its children.

The edge case that catches people

Multi-currency parent with a partial reversal in a third currency. The conversion rate at each step matters. The reconciliation record must preserve the rate used, not just the amount.

Partial reversals are the operation that makes a platform look mature or amateurish. The design is more work; the payoff is that reconciliation doesn't drift.