All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Clawback Event Recording & Reversal Handling

Clawback Event Recording & Reversal Handling

Available from: v1.0.60

The Direct Debit service handles inbound BACS returns and reversals from Modulr automatically. When a tenant's bank reverses a collected payment, the service records a clawback event, adjusts the reserve, and — if the funds have already been forwarded — raises a high-severity alert for manual intervention.

Overview

A clawback occurs when a tenant's bank reverses a Direct Debit payment after it has been collected. This typically happens because:

  • The tenant disputes the charge
  • Insufficient funds were available at the time of settlement
  • The bank identifies an error in the collection

BACS reversals are communicated back to the service via Modulr chargeback webhooks. From v1.0.60, the service fully processes these events end-to-end.

How It Works

1. Webhook Receipt

Modulr sends a chargeback webhook to the service when a BACS return or reversal is received. The service validates the event payload and matches it to the originating collection record using the collection reference.

2. Clawback Event Recording

A clawback event is created and persisted against the matched collection. Each event captures:

  • Reversal amount (in GBP)
  • BACS reason code — the bank-provided reason for the reversal
  • Timestamp — when the reversal was received
  • Source collection reference
  • Mandate reference

This creates a permanent, auditable record of every reversal.

3. Reserve Debiting

The clawback amount is automatically debited from the clawback reserve held in the Griffin DD holding account. This ensures the reserve balance reflects actual exposure at all times.

Note: If the reserve balance falls below the configured minimum threshold following a debit, a reserve-low alert is raised independently via the standard threshold alerting system.

4. Post-Forward Alert Escalation

If the funds from the original collection have already been forwarded to the agent's Griffin client account before the reversal arrives, the service cannot automatically recover the funds from the holding account. In this case:

  • A high-severity alert is created and dispatched to configured alert recipients
  • The alert includes the reversal amount, mandate reference, collection reference, and BACS reason code
  • The alert requires manual acknowledgement via the API or consuming application

This ensures that agents and administrators are immediately notified when a reversal requires manual recovery action.

5. Mandate Clawback Counter

The mandate record is updated each time a clawback event is processed. The clawback_count field on the mandate is incremented, providing a running total of reversals associated with that mandate. This counter can be used by the consuming application to flag high-risk mandates or trigger additional verification.

6. Clawback History in Timeline & Reports

Clawback events are surfaced in two places:

  • Mandate Timeline — Each clawback event appears as a chronological entry in the mandate's activity timeline, alongside mandate creation, collection, and forwarding events.
  • Collection Reports — Collection reports now include a clawback history section, showing all reversals associated with a collection run, including amounts, reason codes, and resolution status.

Alert Severity Reference

ConditionAlert Severity
Clawback received; funds still in holding accountInformational (reserve adjustment only)
Clawback received; funds already forwardedHigh — manual intervention required
Reserve drops below minimum after clawback debitConfigured threshold severity

Mandate Record Fields

The following field is updated on the mandate record when a clawback event is processed:

FieldTypeDescription
clawback_countintegerRunning total of clawback events recorded against this mandate. Incremented on each reversal.

Related