All Docs
FeaturesagentOS Direct DebitUpdated March 12, 2026

Modulr API Integration

Modulr API Integration

Version 1.0.6 introduces the Modulr API client — the integration layer responsible for all communication between the Direct Debit service and Modulr. Modulr is the Direct Debit provider that handles BACS submission, AUDDIS mandate registration, and collection processing.

All operations are org-scoped: every API call is made using the SUN (Service User Number) configured for the originating organisation, ensuring strict multi-tenant isolation.

Capabilities

Account Creation

Modulr accounts can be created programmatically via the client. On successful creation, the Modulr-assigned account ID is written back to the corresponding database record, linking the internal account to its Modulr counterpart.

Mandate Registration (AUDDIS)

New Direct Debit mandates are submitted to Modulr using the AUDDIS process. Once Modulr accepts the submission, the external mandate reference returned by Modulr is stored on the mandate record. This reference is used for all subsequent mandate operations.

Mandate Lifecycle Management

The client exposes dedicated operations for each stage of the mandate lifecycle:

OperationDescription
CancelPermanently cancels a mandate with Modulr.
SuspendTemporarily pauses collections against a mandate.
ReactivateReinstates a previously suspended mandate.

BACS Collection Submission

Collection requests are submitted to Modulr over the BACS cycle. The client handles request formatting and submission, returning a reference that can be used for subsequent status polling.

Payment Status Polling

The client can poll Modulr for the current status of any payment. This is useful for tracking in-flight collections between BACS submission and settlement confirmation.

Webhook Ingestion

Modulr pushes real-time event notifications to the service via webhooks. The following events are handled:

mandate.accepted

Triggered when Modulr confirms a mandate has been successfully registered via AUDDIS. The mandate status is updated to active.

mandate.rejected

Triggered when Modulr rejects a mandate submission. The rejection reason is recorded and the mandate status is updated accordingly. The consuming application can use the gatekeeping API to act on this (e.g. restrict tenant portal access).

collection.settled

Triggered when Modulr confirms that collected funds have settled. This event initiates the downstream sweep of funds from the Modulr collection account into the Griffin DD holding account.

collection.returned

Triggered when a tenant's bank reverses a Direct Debit payment. The returned collection is flagged and the clawback reserve is recalculated.

Org-scoped SUN Configuration

Each organisation (letting agent) has its own SUN registered with Modulr. All client calls include the SUN for the originating org. This means:

  • Collections, mandates, and accounts are always submitted under the correct SUN.
  • There is no shared SUN across organisations.
  • SUN configuration is managed per-org in the organisation settings.

Data Persistence

The integration stores Modulr-assigned identifiers on the relevant database records to maintain the link between internal entities and their Modulr counterparts:

FieldRecordDescription
modulr_account_idAccountThe Modulr account ID returned on account creation.
modulr_external_refMandateThe external reference assigned by Modulr on AUDDIS registration.

These fields are used internally by the service for all subsequent Modulr API operations and should be treated as read-only from the perspective of a consuming application.

Related Topics