All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Mandate Lifecycle Management: Cancel, Suspend & Reactivate

Mandate Lifecycle Management: Cancel, Suspend & Reactivate

Available from: v1.0.45

Once a Direct Debit mandate has been set up, its state can be managed throughout its lifetime using three admin-only tRPC procedures: cancel, suspend, and reactivate. Each transition is validated, fully audited, and communicated to the tenant automatically.

Mandate States

StateDescription
activeThe mandate is live. Collections will run as scheduled.
suspendedCollections are paused. The mandate remains registered with Modulr but no payments will be collected until reactivated.
cancelledThe mandate has been de-registered with Modulr via AUDDIS/BACS. This is a terminal state — it cannot be reversed.

Allowed Transitions

active      → suspended   (suspend)
active      → cancelled   (cancel)
suspended   → active      (reactivate)
suspended   → cancelled   (cancel)

Attempting a transition from an invalid state will return a structured error. No partial state changes occur.

Procedures

All procedures are admin-only. Requests from unauthenticated or non-admin callers are rejected.

mandate.cancel

Permanently cancels a mandate. Calls the Modulr cancel mandate API to de-register the mandate with AUDDIS/BACS, transitions the mandate to cancelled, and fires a webhook so that consuming applications (such as agentOS) can act accordingly — for example, restricting tenant portal access.

Valid from: active, suspended

Effects:

  • Mandate de-registered with Modulr (AUDDIS/BACS).
  • Mandate state set to cancelled.
  • Webhook fired (mandate.cancelled).
  • Audit trail entry created.
  • Tenant notified.

⚠️ Cancellation is irreversible. A new mandate must be created if collections are required in the future.

mandate.suspend

Temporarily pauses all future scheduled collections against a mandate. The mandate remains registered with Modulr and can be reactivated at any time.

Valid from: active

Effects:

  • Future collections suspended immediately.
  • Mandate state set to suspended.
  • Audit trail entry created.
  • Tenant notified.

Collections that have already been submitted to BACS are not affected by a suspension.

mandate.reactivate

Re-enables a previously suspended mandate, restoring scheduled collections.

Valid from: suspended

Effects:

  • Collections re-enabled.
  • Mandate state set to active.
  • Audit trail entry created.
  • Tenant notified.

Audit Trail

Every state transition is recorded in the mandate audit trail. Each entry captures:

  • Timestamp — when the transition occurred.
  • Actor — the admin who initiated the transition.
  • Previous state — the state before the transition.
  • New state — the state after the transition.

Audit entries are immutable and cannot be deleted.

Tenant Notifications

Tenants are automatically notified whenever a mandate state changes. Notifications inform the tenant of the nature of the change (suspension, reactivation, or cancellation) so they are aware of the status of their Direct Debit.

Webhooks

The mandate.cancel procedure fires a webhook event that consuming applications can subscribe to. This enables downstream systems to react to mandate cancellations — for example, agentOS can use this event to trigger tenant portal gatekeeping (blocking access until a new mandate is established).

EventTrigger
mandate.cancelledFired when a mandate is successfully cancelled.

Error Handling

If a transition is attempted from an invalid state, the procedure returns a structured error indicating the current state and the reason the transition was rejected. No changes are made to the mandate when an error is returned.