All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Collection Status Polling & Confirmation Job

Collection Status Polling & Confirmation Job

Introduced in v1.0.38

The collection status polling job is the automated engine that drives a collection record through its lifecycle after a BACS submission has been made to Modulr. It uses Inngest for both event-driven and scheduled (cron) execution, removing the need for any manual intervention once a collection has been initiated.

How It Works

1. Polling Trigger

A cron-based Inngest job runs on a recurring schedule and queries Modulr for the current status of all outstanding (pending) collection records. It can also be triggered immediately via an Inngest event if a status check is needed outside the cron window.

2. Status Evaluation

Modulr returns one of three terminal statuses for a collection:

Modulr StatusMeaning
paidFunds have been successfully debited from the tenant's account
failedThe collection attempt was rejected or dishonoured
returnedFunds were collected but subsequently reversed/returned by the tenant's bank

3. Successful Collection Path (paid)

When Modulr confirms a collection as paid:

  1. The collection record is updated to collected status in the database.
  2. A sweep-to-holding Inngest event is fired, which triggers the fund sweep from the Modulr collection account into the Griffin DD holding account.
  3. The hold period and clawback reserve logic then take over from this point forward.

4. Failed Collection Path (failed / returned)

When Modulr reports a collection as failed or returned:

  1. The collection record is updated to failed status in the database.
  2. A failed-collection alert is raised — stored in the system and sent via email to all configured alert recipients for the relevant customer.
  3. A gatekeeping flag is set on the associated mandate via the API. Consuming applications can read this flag to restrict access (e.g. blocking a tenant's portal login) until a valid mandate and successful collection are re-established.

Inngest Job Summary

Type:    Cron + Event-driven (Inngest)
Triggers:
  - Scheduled cron (recurring interval)
  - Inngest event: collection/status.check
Actions:
  - Polls Modulr collection status API
  - Transitions collection record state
  - Emits sweep-to-holding event (on success)
  - Raises failed-collection alert (on failure)
  - Sets gatekeeping flag (on failure)

State Transitions

[pending]
    │
    ├──(paid)──────────► [collected] ──► sweep-to-holding event
    │
    └──(failed/returned)► [failed]   ──► alert raised
                                     ──► gatekeeping flag set

Gatekeeping Flag

When a collection fails, the service exposes a gatekeeping flag against the mandate via the API. This is designed to be consumed by an external application (such as agentOS) to enforce access restrictions until the situation is resolved.

See the Admin API reference for details on how to read and clear gatekeeping flags.

Alerts

Failed collection alerts follow the same alerting model as other threshold-based alerts in the service. They are:

  • Stored persistently in the alerts table, scoped to the relevant customer.
  • Emitted via email to all configured alert recipients for that customer.
  • Acknowledgeable via the admin API.

Related