All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Clawback Handling & Reversal Processing

Clawback Handling & Reversal Processing

The Direct Debit service automatically handles clawback events — situations where a tenant's bank reverses a previously collected payment. This page describes how clawbacks are detected, processed, and how the system protects the reserve.

What Is a Clawback?

A clawback (also called a reversal or return) occurs when a collected Direct Debit payment is reversed by the paying bank after it has cleared. Common reasons include:

Reason CodeDescription
instruction_cancelledThe mandate was cancelled by the payer or their bank
no_accountThe bank account no longer exists
insufficient_fundsInsufficient funds at the time of reversal
payer_deceasedAccount holder is deceased
bank_requestReversal requested by the bank

How Clawbacks Are Processed

Clawbacks arrive as Modulr webhook callbacks. When the service receives a clawback webhook, it executes the following steps in order:

1. Collection Status Transition

The affected collection record is moved to clawback status:

collection.status: "collected" → "clawback"

This status change is immediately visible via the collections API and prevents the collection from being forwarded.

2. Reserve Deduction

The clawback amount is deducted from the clawback reserve held in the Griffin DD holding account. The reserve absorbs the loss, protecting the agent's client account from being debited for a payment that has been reversed.

3. Reversal Reason Logging

The reversal reason code supplied by Modulr is recorded against the collection record. This provides a full audit trail of why the payment was returned.

4. Mandate Clawback Count Update

The originating mandate's clawback_count is incremented. This counter can be used by consuming applications (e.g. agentOS) to identify tenants with a history of reversals and take appropriate action — such as flagging the mandate or restricting portal access.

5. clawback_received Alert

A clawback_received alert is raised automatically. The alert payload includes:

  • The affected collection ID
  • The mandate ID
  • The reversed amount (GBP)
  • The reversal reason code
  • The timestamp of the webhook

Configured alert recipients are notified by email. Alerts can also be retrieved and acknowledged via the Alerts API.

Reserve Depletion & Forwarding Suspension

If a clawback causes the clawback reserve to drop below the configured minimum threshold, the service automatically suspends all further fund forwarding from the Griffin holding account.

reserve_balance < minimum_threshold → forwarding SUSPENDED

Forwarding remains suspended until the reserve is replenished above the minimum threshold. This protects agents from receiving funds that may subsequently be clawed back.

Note: The minimum threshold and risk factor used to calculate reserve requirements are configurable per customer. See Clawback Reserve Configuration for details.

Clawback Flow Summary

Modulr webhook (reversal)
        │
        ▼
[1] Transition collection → clawback status
        │
        ▼
[2] Deduct amount from Griffin holding reserve
        │
        ▼
[3] Log reversal reason code
        │
        ▼
[4] Increment mandate clawback_count
        │
        ▼
[5] Raise clawback_received alert → email notification
        │
        ▼
[6] Check reserve vs. minimum threshold
        │
   ┌────┴────┐
 reserve OK  reserve depleted
        │           │
        │     SUSPEND forwarding
        ▼
  (continue)

Related