Per-Org DD Configuration & SUN Management — v1.0.9

Per-Org DD Configuration & SUN Management

Released in v1.0.9

Every letting agent operating on the platform has distinct banking relationships, risk appetites, and branding requirements. v1.0.9 introduces a dedicated Direct Debit configuration block on each organisation record, giving you full per-tenant control over every aspect of the DD collection pipeline — from provider account references to clawback reserve rules and alert recipients.

Configuration Fields

Provider Account References

These fields wire an organisation's configuration to the correct accounts at each provider. They must be set before any collection activity can occur.

Field	Type	Description
`modulrSun`	`string`	Modulr Service User Number — the 6-digit identifier registered with Bacs that authorises the organisation to collect Direct Debits. Must be exactly 6 digits.
`modulrCollectionAccountId`	`string`	The Modulr account ID into which collected tenant payments land after a BACS run.
`griffinHoldingAccountId`	`string`	The Griffin account used to hold funds during the configured hold period before forwarding.
`griffinClientAccountId`	`string`	The Griffin client account into which funds are released once the hold period and clawback reserve conditions are satisfied.

Fund-Flow Timing

Field	Type	Default	Description
`holdPeriodHours`	`integer`	`24`	How long (in hours) collected funds are held in the Griffin holding account before being forwarded to the client account. Increase this to extend clawback protection.

Clawback Reserve

The clawback reserve is a buffer maintained in the Griffin holding account to absorb any payment reversals initiated by a tenant's bank.

Field	Type	Description
`clawbackReserveRiskFactor`	`decimal`	A multiplier applied to recent collection volume to calculate the dynamic reserve requirement.
`clawbackReserveMinGbp`	`decimal`	The absolute minimum GBP amount the reserve must hold, regardless of collection volume.

Funds are only forwarded to the client account once both the risk-factor-derived amount and the minimum threshold are satisfied.

Alerting

Field	Type	Description
`alertRecipientEmails`	`string[]`	One or more email addresses that receive threshold breach and fraud alerts for this organisation.

Mandate Form Branding

Field	Type	Description
`mandateFormBranding`	`object`	Branding configuration (e.g. logo, colours) applied to the public-facing mandate setup form presented to tenants.

Reading & Updating Config via tRPC

Two admin-scoped tRPC procedures expose this configuration over the API.

`org.getDdConfig`

Returns the full DD configuration object for the authenticated organisation.

const config = await trpc.org.getDdConfig.query();

// Example response
{
  modulrSun: "123456",
  modulrCollectionAccountId: "acc_modulr_abc123",
  griffinHoldingAccountId: "acc_griffin_hold_xyz",
  griffinClientAccountId: "acc_griffin_client_xyz",
  holdPeriodHours: 24,
  clawbackReserveRiskFactor: 0.05,
  clawbackReserveMinGbp: 500.00,
  alertRecipientEmails: ["finance@agency.co.uk"],
  mandateFormBranding: { ... }
}

`org.updateDdConfig`

Partially or fully updates the DD configuration for the authenticated organisation. Only the fields you supply are updated.

await trpc.org.updateDdConfig.mutate({
  holdPeriodHours: 48,
  clawbackReserveMinGbp: 1000.00,
  alertRecipientEmails: [
    "finance@agency.co.uk",
    "ops@agency.co.uk"
  ]
});

Validation Rules

modulrSun — must be a string of exactly 6 digits (e.g. "123456"). Any value that is shorter, longer, or contains non-digit characters will be rejected with a validation error.

Defaults

For organisations that do not explicitly configure holdPeriodHours, the system defaults to 24 hours. All other fields must be set explicitly before collections can run.

Multi-Tenancy

All DD configuration is strictly scoped to the organisation. There is no shared or inherited configuration between organisations. Each organisation must independently configure its own SUN, account IDs, reserve rules, and alert recipients.