> ## Documentation Index
> Fetch the complete documentation index at: https://corridor.udokaam.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Failure and compensation

> A partner fails mid-payout. The saga undoes every completed step in reverse order, including a real on-chain refund on Tempo, and the customer ends exactly where they started.

Payments fail. What matters is where the money is afterwards, and whether the books say so. This walkthrough is the console action **Payout with partner failure**, which injects a failure at `partner.payout` (`faults.failAt`). It ran three times on testnet; each run compensated cleanly.

## The run

EUR → NGN, 4 pathUSD, recorded on 29 September 2026:

<Frame caption="Fig. 07 · Forward legs, a failure at the partner, and compensation in reverse order with an on-chain refund.">
  <img className="block dark:hidden" src="https://mintcdn.com/corridorapp/YeOtjsXcStLLcZ_W/images/diagrams/saga-compensation-light.svg?fit=max&auto=format&n=YeOtjsXcStLLcZ_W&q=85&s=acf04658e2a93a7fb2a9d0ee29cf8b9a" alt="Saga forward steps and reverse compensation" width="1200" height="480" data-path="images/diagrams/saga-compensation-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/corridorapp/YeOtjsXcStLLcZ_W/images/diagrams/saga-compensation-dark.svg?fit=max&auto=format&n=YeOtjsXcStLLcZ_W&q=85&s=99b260eb8221ddbb91c51bd63933c824" alt="Saga forward steps and reverse compensation" width="1200" height="480" data-path="images/diagrams/saga-compensation-dark.svg" />
</Frame>

```mermaid theme={"dark"}
sequenceDiagram
  participant S as Saga
  participant L as Ledger
  participant T as Tempo
  S->>L: reserve 4 pathUSD (available → hold)
  S->>T: bridge out: treasury → escrow, reference memo
  S->>L: book bridge.deposit + bridge.fill
  S--xS: partner.payout fails (injected)
  Note over S: compensate in reverse order
  S->>T: refund: escrow → treasury, same reference memo
  S->>L: book bridge.unfill + bridge.refund
  S->>L: release hold (hold → available)
  Note over S: status: compensated
```

| Step | Forward | Compensation |
| - | - | - |
| `ledger.reserve` | Available → hold | Hold → available (`payout.release`) |
| `bridge.simulated` | Treasury → escrow on Tempo ([0xb13fd060…](https://explore.testnet.tempo.xyz/tx/0xb13fd06043c4647bbcdeb9e53313f02f845443e8ddcd17a57a468758a8ae229d)) | Escrow → treasury refund ([0x67790303…](https://explore.testnet.tempo.xyz/tx/0x6779030377fb90884212fa7f5d3acc681958856b7ce22406862f7d2e0940c944)) |
| `partner.payout` | **Failed** | Nothing to undo |

## Why reverse order

Compensations run from the last completed step to the first. Unwinding the hold before the bridge refund would let the customer's balance show funds that are still in the escrow, and the ledger would balance while describing a sequence that never happened. In reverse order, every intermediate state is one that really existed.

## When not to compensate

If the partner fails **after** it was funded, the money is at the partner, not with Corridor. Reversing Corridor's books at that point would be wrong until the partner's refund is confirmed, so the payout leg throws `ManualReviewError`: no retries, no automatic compensation, and the saga waits in `manual_review` for a person to close it against the partner's refund.

## The result

| | Before | After |
| - | - | - |
| Customer available | X | X |
| Customer hold | 0 | 0 |
| Treasury vault on Tempo | Y | Y (refund received) |
| Saga status | | `compensated` |

The Tempo deposit and its refund both carry the payout's reference, so reconciliation matches both movements to the forward and compensating entries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.