All Docs
FeaturesagentOS Direct DebitUpdated March 12, 2026

Modulr API Integration Client

Modulr API Integration Client

Introduced in v1.0.8

The Modulr API client is the server-side integration layer between the Direct Debit service and Modulr — the BACS Direct Debit provider responsible for mandate registration, BACS submission, and collection processing.

All interaction with Modulr is routed through this client. It handles authentication, request signing, error normalisation, and retry logic so that the rest of the service can call Modulr operations without dealing with transport-level concerns.

Configuration

The client is configured via environment variables. These must be set before the service starts.

VariableDescription
MODULR_BASE_URLBase URL for the Modulr API. Use the sandbox URL during development and the production URL in live environments.
MODULR_API_KEYAPI key issued by Modulr. Included in the Authorization header of every request.
MODULR_SIGNING_SECRETSigning secret issued by Modulr. Used to generate the HMAC signature attached to each request.

Operations

Mandate Registration (AUDDIS Submission)

Submits a new Direct Debit mandate to Modulr for registration via the AUDDIS scheme.

  • Accepts typed mandate data (payer details, bank details, collection amount/frequency, SUN).
  • Returns a typed response containing the Modulr mandate reference.
  • The mandate reference should be persisted locally and used for all subsequent operations against that mandate.

Mandate Cancellation

Permanently cancels a registered mandate with Modulr.

  • Accepts the Modulr mandate reference.
  • Once cancelled, a mandate cannot be reactivated — a new mandate must be submitted.

Mandate Suspension

Temporarily suspends an active mandate.

  • Collections will not be submitted against a suspended mandate.
  • A suspended mandate can be reactivated.

Mandate Reactivation

Reactivates a previously suspended mandate.

  • Returns the mandate to active status so that collections can resume.

Collection Submission

Submits a BACS collection request to Modulr against a registered, active mandate.

  • Accepts the mandate reference, collection amount, and collection date.
  • Returns a typed response containing the Modulr collection reference.
  • The collection reference should be persisted and used for subsequent status polling.

Collection Status Polling

Polls Modulr for the current processing status of a submitted collection.

  • Accepts the Modulr collection reference.
  • Returns the current status (e.g. submitted, pending, collected, failed, returned).
  • Used by the service to determine when funds have been collected and are ready to sweep to the Griffin holding account.

Account Balance Query

Queries the balance of a Modulr account.

  • Accepts the Modulr account ID.
  • Returns the current available balance in GBP.
  • Used to inform sweep decisions and clawback reserve calculations.

Request Signing

Every outbound request to the Modulr API is signed using the MODULR_SIGNING_SECRET. The signature is computed as an HMAC and attached to the request headers in the format Modulr requires. This satisfies Modulr's security requirements and ensures requests cannot be tampered with in transit.

Error Normalisation

The client catches all errors returned by the Modulr API — whether HTTP-level (4xx, 5xx) or API-level (Modulr error codes) — and maps them to a consistent internal error structure. This means call sites across the service receive predictable error objects regardless of the nature of the underlying failure.

Normalised errors include:

  • The original Modulr error code (where available)
  • A human-readable message
  • The HTTP status code
  • Whether the error is considered retryable

Retry Logic

The client includes built-in retry logic for transient failures. Requests that fail due to network timeouts or temporary Modulr unavailability are automatically retried, reducing noise from intermittent errors and minimising the need for manual intervention.

Retries are only attempted for errors flagged as retryable (e.g. network errors, 5xx responses). Errors that indicate a permanent failure (e.g. invalid mandate reference, authentication failure) are not retried.

Relationship to the Fund Flow

The Modulr client is involved at several stages of the fund flow:

  1. Mandate Setup — The client submits the new mandate to Modulr via AUDDIS.
  2. Collection — The client submits the collection request to Modulr via BACS.
  3. Status Monitoring — The client polls Modulr until the collection status confirms funds have been collected.
  4. Sweep Trigger — Once collection is confirmed, the service uses the account balance query to verify funds are present before initiating the sweep to Griffin.
  5. Mandate Lifecycle — The client handles any suspension, reactivation, or cancellation instructions issued by the service.