All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Fund Forwarding: From DD Holding to Agent Client Account

Fund Forwarding: From DD Holding to Agent Client Account

Overview

Once collected funds have been held in the Griffin DD holding account for the required hold period — and the organisation's clawback reserve is satisfied — the service automatically forwards those funds into the agent's Griffin client account, completing the rent collection cycle.

This step is handled by an hourly Inngest cron job introduced in v1.0.52.

How It Works

1. Hourly Cron Sweep

Every hour, the Inngest job scans all pending sweeps and identifies those that meet both forwarding conditions:

ConditionDescription
hold_until has passedThe configured hold period (default: 24 hours) has elapsed since funds arrived in the holding account
Clawback reserve satisfiedThe organisation's holding account balance exceeds the calculated clawback reserve threshold

Only sweeps meeting both conditions are eligible for forwarding in that cycle.

2. Griffin Payment Initiation

For each eligible sweep, the service initiates a payment via Griffin from the DD holding account to the agent's Griffin client account. Each forwarding action is recorded as a forward_payment entry, capturing:

  • Source sweep reference
  • Amount forwarded
  • Destination client account
  • Timestamp and status

3. Partial Forwarding

If the clawback reserve constraint means only a portion of the held funds can be released, the service forwards the eligible amount immediately and defers the remainder to a future cron cycle. This prevents the reserve from being depleted below the required minimum.

Example:

Holding account balance:    £10,000
Clawback reserve required:   £2,500
Maximum forwardable:         £7,500

If pending sweep = £10,000:
  → Forwards:  £7,500  (this cycle)
  → Deferred:  £2,500  (next eligible cycle)

4. Settlement Confirmation

Once Griffin confirms the payment, the system marks the associated collection as fully settled. This confirmation step is handled asynchronously, so payment initiation and settlement are tracked independently.

Fund Flow Summary

Tenant bank account
       │
       │  BACS collection (Modulr)
       ▼
Modulr collection account
       │
       │  Sweep (on collection confirmation)
       ▼
Griffin DD holding account
       │
       │  Forward (hourly cron, after hold_until + reserve check)
       ▼
Agent's Griffin client account  ✓ Settled

Clawback Reserve

The clawback reserve is a balance maintained in the holding account to cover potential reversals from tenant banks. The reserve amount is organisation-specific and is calculated using a configurable risk factor and minimum threshold.

The forwarding job will never release funds that would cause the holding account balance to fall below the reserve requirement. If reserve conditions are not met, the sweep remains pending and is re-evaluated on the next hourly run.

Audit Trail

Every forwarding action produces a forward_payment record. These records are queryable via the API and provide a complete history of:

  • When each forward was initiated
  • How much was forwarded
  • Which sweep and collection the forward relates to
  • The current status (pending, confirmed, failed)

Configuration

ParameterDescriptionDefault
Hold periodMinimum time funds sit in holding before forwarding24 hours
Clawback reserve factorRisk multiplier used to calculate reserve requirementPer-org config
Clawback reserve minimumAbsolute floor for the reserve balancePer-org config
Cron frequencyHow often the forwarding job runsHourly

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

Related Features