v1.0.44 — Clawback Reserve Calculation & Enforcement

Blog post · Direct Debit Collection Service

One of the most important risk controls in any Direct Debit operation is the clawback reserve — the cushion of funds that protects against reversed payments. With v1.0.44, the Direct Debit Collection Service now calculates, enforces, and monitors this reserve automatically.

The Problem

Direct Debit payments are not instant and are not irrevocable. A tenant's bank can reverse a collection — a "clawback" — for several days after it has been processed. If funds have already been forwarded to an agent's client account by the time the clawback arrives, the service is left out of pocket.

The solution is to hold back a portion of collected funds until the risk window has passed. But doing this manually is error-prone and doesn't scale across multiple organisations, each with different collection volumes and risk tolerances.

What We Built

A Per-Organisation Reserve Formula

The service now calculates a required reserve for each organisation:

reserve = max(minimum_threshold, total_pending_funds × risk_factor)

Both minimum_threshold (an absolute GBP floor) and risk_factor (a percentage of pending funds) are configurable per organisation. This means a high-volume agent will automatically hold more in reserve than a smaller one — proportionally and appropriately.

Automatic Enforcement After Every Sweep

Every time funds are swept from the Modulr collection account into the Griffin DD holding account, the reserve is recalculated. From that point, the forward-to-client step will only proceed if:

Griffin holding balance ≥ reserve

If the balance doesn't cover the reserve, the forward is blocked — automatically, with no manual intervention needed.

Audit Trail

Every reserve calculation is snapshotted and stored. This gives a complete, timestamped audit history of reserve levels, the inputs used, and whether the reserve was satisfied at each point in time. This matters for compliance and for diagnosing any anomalies after the fact.

Alerting When the Reserve Falls Short

If the holding balance drops below the configured minimum threshold — most likely because a clawback has been processed — an alert is raised and sent to configured recipients. The existing alert infrastructure handles delivery and acknowledgement.

Reserve Status in the API

The current reserve status is now exposed via both the REST API (GET /reserve/status) and the internal tRPC interface. Consuming applications like agentOS can surface this in dashboards, giving agents and platform operators a live view of reserve health.

Why It Matters

This release closes a significant gap in the fund flow: funds were previously swept and forwarded without an automated financial safety check. With v1.0.44, the service enforces the reserve requirement at every forwarding decision — making the clawback protection systematic rather than procedural.

What's Next

Future iterations may include configurable hold periods tied to reserve satisfaction, per-mandate risk scoring, and more granular reporting on clawback history and reserve utilisation.

---

For full technical details, see the Clawback Reserve feature documentation.