Full Audit Trail for Direct Debit Operations

Release v1.0.49

Operating a Direct Debit collection service means handling real money moving through multiple systems on behalf of real people. When something goes wrong — or when a regulator, auditor, or support engineer asks exactly what happened and when — you need a complete, trustworthy record. With v1.0.49, every meaningful operation in the DD lifecycle now produces a structured audit event.

What Changed

Previous releases included a general-purpose audit log. This release extends it to cover the full spectrum of DD-specific operations, from the moment a tenant submits a mandate form all the way through to funds being confirmed in an agent's client account — and every state transition in between.

Fifteen new event types have been added:

mandate_submitted
mandate_activated
mandate_cancelled
mandate_suspended
mandate_reactivated
collection_scheduled
collection_submitted
collection_settled
sweep_initiated
sweep_confirmed
forward_initiated
forward_confirmed
clawback_received
alert_raised
alert_acknowledged

Consistent, Structured Metadata

Every event carries a standard set of fields so you can reliably filter, query, and correlate records across the system:

{
  "event": "collection_settled",
  "actor": "system",
  "org": "org_abc123",
  "resource_id": "col_xyz789",
  "amount": 120000,
  "timestamp": "2025-07-15T09:14:02Z"
}

• actor distinguishes between automated system operations and actions taken by a specific user (by user ID). You can tell at a glance whether a mandate was cancelled by a human or by an automated process.
• org scopes every event to the originating letting agent, maintaining strict multi-tenant data isolation.
• resource_id ties the event back to the specific mandate, collection, sweep, or alert it relates to.
• amount is included on all financial events — collections, sweeps, forwards, and clawbacks — in pence (GBP).

Coverage Across the Full Fund Flow

The new events map directly onto the end-to-end fund flow described in the service architecture:

1. Mandate lifecycle — mandate_submitted → mandate_activated, with mandate_cancelled, mandate_suspended, and mandate_reactivated covering post-activation state changes.
2. Collection — collection_scheduled → collection_submitted → collection_settled tracks the BACS submission cycle.
3. Sweep — sweep_initiated → sweep_confirmed records the movement of funds from Modulr into the Griffin DD holding account.
4. Forward — forward_initiated → forward_confirmed records the release of held funds to the agent's Griffin client account.
5. Clawback — clawback_received captures any bank-initiated reversals, critical for reserve management and reconciliation.
6. Alerts — alert_raised and alert_acknowledged provide a complete record of threshold breaches and their resolution.

Why This Matters

Compliance & Audit Readiness A complete event log makes it straightforward to answer questions from auditors, regulators, or your own compliance team: when was this mandate activated? Who cancelled it? When did these funds move, and how much?

Debugging & Support When a collection doesn't arrive when expected, support teams can trace the exact sequence of events — scheduled, submitted, settled, swept — without needing database access or code instrumentation.

Multi-Tenant Isolation The org field on every event means audit queries are always scoped to a single letting agent. There is no risk of one customer's audit data leaking into another's.

Fraud & Anomaly Investigation Having alert_raised and alert_acknowledged in the audit trail means you can see not just that an alert fired, but when it was noticed and by whom — useful evidence in any fraud investigation.

Accessing Audit Events

Audit events are available via the existing audit log API. You can filter by:

• event type (e.g. mandate_submitted, clawback_received)
• org (your organisation's ID)
• actor (a specific user ID, or system)
• resource_id (a specific mandate, collection, or alert)

No schema changes are required — the new events are fully additive to the existing log.