Reverse a payment
Why there is no reverse-payment command—posted payments unwind through the provider-driven return flow, and ledger corrections use specific governed commands.
A posted payment reverses in exactly one way: the payment provider reports a return—an ACH return or card chargeback—and the payment return flow unwinds the posting. Everything else is a forward-posting correction through a specific governed command.
- Settled debit postssettled moneyautomatic
- Provider reports a returnACH return or card chargebackwaits
- Posting unwounda linked reversal, never a negative paymentautomatic
- Delinquency recalculatedfrom authoritative posted historyautomatic
Why the command does not exist
A posted payment is settled money with a posted allocation. Letting an operator “reverse” it directly would fabricate a money movement the rails never saw, and the ledger would immediately disagree with the bank. The platform therefore splits the problem:
The money genuinely came back
- The provider return flow records it
- The payment moves to RETURNED with its provider reference
The money stayed
- A governed adjustment or credit command corrects it
Provider-driven returns
Return-code policy decides the consequences: whether retry is allowed (a new intent linked by retryRootPaymentId), whether the instrument is invalidated, and how autopay reacts. An unfamiliar return code fails closed to review.
Suppose a $517.14 Harbor debit is returned for insufficient funds. The original payment and its receipt remain visible, and the reversal restores the allocation components under the loan’s replay rules. A customer conversation (“I dispute that payment”) routes to the provider dispute process, not to an API mutation.
Correcting the ledger without a return
When the books are wrong but money did not come back, use the command whose economic meaning matches:
| Situation | Correct mechanism |
|---|---|
An externally recorded payment (record-external) was posted in error |
Raise it in reconciliation; the correction posts under a recon exception, not a payment mutation. |
| A fee that was paid must be returned | chargeRefund posts the credit. |
| The borrower overpaid and holds a credit balance | creditBalanceRefund with a REFUND funding. |
| The lender owes value for a service failure | goodwillCredit. |
| Money arrives on a charged-off loan | recoverypayment—not a repayment, not a reversal. |
Each command carries its own permission and writes a governance record. None of them edits the original payment.
A payment that has not posted yet
A payment still in flight is not reversed—it either completes or fails on its own lifecycle. There is no public cancel route; intervene through the case so the outcome is recorded. Only the posted result is ever corrected, and only through the paths above.
What stays visible
However the correction happens, the original payment, its receipt, and its timeline remain readable. Reporting distinguishes money that bounced from books that were fixed—that distinction is the point.