Sending Mandate Invites to Tenants

Version 1.0.13 introduces the mandate invite flow — an admin-only mechanism for letting agents to send tenants a secure, personalised link to complete their Direct Debit mandate setup.

Overview

When a letting agent wants to collect rent via Direct Debit, they trigger a mandate invite for the relevant tenant. The service generates a secure token, stores it, and emails the tenant a unique link. The tenant follows that link to complete the multi-step mandate form at their own pace.

The entire flow is initiated through a single tRPC procedure and requires no manual token handling by the agent.

How It Works

Agent triggers the invite — An admin calls the sendMandateInvite tRPC procedure, providing the tenant's email address, the expected collection amount, the payment frequency, and the day-of-month for collections.
Token is generated and stored — The service creates a cryptographically secure, single-use token and persists it in the mandate_invite_tokens table, scoped to the agent's organisation.
Email is sent to the tenant — The tenant receives an email containing a unique mandate form URL in the format /mandate/[token].
Tenant completes the form — The tenant follows the link and works through the mandate setup steps. The token is consumed on submission, preventing reuse.
Token expiry — If the tenant does not complete the form within 7 days, the token expires and the agent must issue a new invite.

Token Properties

Property	Value
Expiry	7 days from generation
Single-use	Yes — invalidated on form submission
Scoped to	Organisation + tenant email
Linked data	Amount, payment frequency, collection day-of-month

Mandate Variants

The invite supports two mandate variants, determined at token generation time:

Property mandate — Includes the Right to Rent verification step in the mandate form. Use this for residential tenancy agreements.
Non-property mandate — Omits the Right to Rent step. Use this for non-tenancy payment arrangements.

The correct form variant is served automatically based on the token metadata — no action is required from the tenant.

Access Control

The sendMandateInvite procedure is admin-only. It must be called with valid admin credentials scoped to the relevant organisation. Tokens are strictly scoped per organisation — a token generated for one organisation cannot be used to submit a mandate under another.

Token Lifecycle

Agent calls sendMandateInvite
        │
        ▼
Token generated → stored in mandate_invite_tokens
        │
        ▼
Invite email sent to tenant (link: /mandate/[token])
        │
        ├── Tenant completes form → token consumed (single-use)
        │
        └── 7 days pass without completion → token expires

Error Cases

Expired token — The mandate form will reject the request and display an expiry message. The agent must generate a new invite.
Already-used token — Attempting to reuse a consumed token will return an error. Each invite requires a fresh token.
Unauthorised access — Calling the procedure without admin credentials will return an authorisation error.