Failed Collection Alerts & Tenant Retry Emails
Failed Collection Alerts & Tenant Retry Emails
When a Direct Debit collection fails, the service automatically notifies the relevant organisation recipients and — optionally — the tenant, so that recovery action can be taken quickly.
How It Works
An Inngest background function listens for collection status transitions to failed. When triggered, it:
- Sends an alert email to all configured recipients for the organisation
- Optionally sends a notification email to the tenant with a link to update their bank details
- Records the failure against the mandate record
Organisation Alert Email
The alert email is sent automatically to all email addresses configured as recipients for the organisation. It contains the following information:
| Field | Description |
|---|---|
| Tenant name | The name of the tenant associated with the failed collection |
| Property reference | The property or mandate reference |
| Amount | The value of the collection that failed |
| Failure reason | The reason returned by Modulr (e.g. insufficient funds, account closed) |
| Mandate link | A direct link to the mandate record in the admin interface |
Recipients are configured per organisation (customer/letting agent). See your organisation settings to manage alert recipients.
Tenant Notification Email (Optional)
An optional notification email can be sent to the tenant informing them of the failed collection. This email:
- Is customisable — organisations can tailor the message content
- Includes a link for the tenant to update their bank details
- Automatically generates a new mandate form token when triggered, initiating a fresh mandate setup flow for the tenant
This allows the tenant to complete a new mandate without any manual intervention from the agent.
Enabling Tenant Notifications
The tenant notification email is opt-in. Whether it is sent is controlled per collection event — consult the API reference for the relevant configuration flag when processing failed collections.
Mandate Record Tracking
Every failed collection is recorded on the associated mandate record. This provides a persistent audit trail of failures, which is accessible via the mandate detail endpoint and visible in the admin interface.
Failure Reasons
Failure reasons are sourced directly from Modulr and reflect standard BACS return codes. Common examples include:
- Insufficient funds — the tenant's account did not have enough funds on the collection date
- Account closed — the tenant's bank account has been closed
- Instruction cancelled — the mandate was cancelled at the tenant's bank
- No account / wrong account number — the bank details on the mandate are invalid
The exact reason string is included in both the organisation alert email and the mandate record.