All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Hold Period Timer & Clawback Reserve — How It Works

Hold Period Timer & Clawback Reserve — How It Works

Introduced in v1.0.51, the hold period timer and clawback reserve calculation are the core mechanisms that protect the platform — and agents — from financial exposure caused by reversed or failed Direct Debit collections.

Overview

After funds are swept from the Modulr collection account into the Griffin DD holding account, two things happen automatically:

  1. A clawback reserve check is performed to determine whether there is enough of a buffer in the holding account to absorb potential reversals.
  2. If the reserve is satisfied, a delayed forward step is scheduled to release funds to the agent's client account after the configured hold period.

If the reserve is not satisfied, the forward is withheld and a reserve_low alert is raised.

The Hold Period Timer

The timer is implemented as an Inngest function that fires after each successful sweep. It schedules the forward step to execute org.holdPeriodHours from the time the sweep completes.

  • org.holdPeriodHours is configured per organisation (letting agent).
  • The default is 24 hours, giving the BACS network sufficient time to surface any clawbacks before funds are released.
  • The forward step only executes if the reserve requirement is still satisfied at the time it runs.

Clawback Reserve Calculation

The required reserve is calculated as:

reserve_required = max(org.clawbackMinGBP, totalOutstandingCollections × org.riskFactor)

Parameters

ParameterDescription
org.clawbackMinGBPMinimum absolute reserve in GBP, configured per organisation. Acts as a floor regardless of collection volume.
org.riskFactorA decimal multiplier (e.g. 0.05 = 5%) applied to the total value of outstanding collections.
totalOutstandingCollectionsThe total GBP value of collections that are within the hold period and not yet forwarded.

Example

Given:

  • org.clawbackMinGBP = £500
  • org.riskFactor = 0.05 (5%)
  • totalOutstandingCollections = £8,000
reserve_required = max(£500, £8,000 × 0.05)
                 = max(£500, £400)
                 = £500

In this case the minimum floor applies. If outstanding collections were £12,000:

reserve_required = max(£500, £12,000 × 0.05)
                 = max(£500, £600)
                 = £600

Here the risk-factor-based amount exceeds the floor, so £600 must remain in the holding account.

What Happens When the Reserve Is Insufficient

If the holding account balance would fall below reserve_required after releasing funds:

  1. The forward step is not scheduled.
  2. A reserve_low alert is raised and stored in the system.
  3. Configured alert recipients are notified by email.
  4. The reserve is re-evaluated automatically when the next collection completes — if the reserve is then satisfied, the forward can proceed.

Reserve Re-Evaluation

The reserve check does not only run at sweep time. It is re-evaluated on every new collection. This means:

  • As more tenant payments are collected and land in the holding account, the available balance grows.
  • If a previously insufficient reserve becomes satisfied by the additional funds, the system can schedule the held forward without manual intervention.

Decision Flow

Sweep completes
      │
      ▼
Calculate reserve_required
      │
      ▼
Holding balance ≥ reserve_required?
    │               │
   YES              NO
    │               │
    ▼               ▼
Schedule forward   Raise reserve_low alert
after holdPeriod   Hold funds
                   Re-evaluate on next collection

Configuration Reference

These values are set per organisation and can be updated via the API.

FieldTypeDescription
holdPeriodHoursintegerHours to hold funds after sweep before forwarding
clawbackMinGBPdecimalMinimum reserve floor in GBP
riskFactordecimalFraction of outstanding collections to hold in reserve

Related Topics