Griffin API Integration — Dylan's Amazing SaaS Factory Docs

Griffin API Integration

The Direct Debit service uses Griffin as its banking and fund-holding provider. A typed API client handles all communication with Griffin, covering account management, payment leg creation, balance queries, and asynchronous payment confirmation.

Overview

Griffin sits at the heart of the fund-holding stage of the collection flow. Once Modulr confirms that tenant funds have been collected, the service uses the Griffin client to:

Sweep funds from the Modulr collection account into a Griffin DD holding account.
Hold those funds for the configured hold period (default: 24 hours) while the clawback reserve is evaluated.
Forward funds from the holding account into the agent's Griffin client account once all conditions are met.

Capabilities

DD Holding Account Creation

Holding accounts are created programmatically via the Griffin API. When a new organisation (letting agent) is onboarded, a dedicated DD holding account is provisioned and the returned Griffin account ID is stored on the organisation's config record.

This account ID is used for all subsequent payment leg operations and balance checks for that organisation.

Payment Legs

Payment movements in Griffin are modelled as payment legs. The client supports two distinct leg types:

Sweep: Modulr → Griffin Holding

Triggered once Modulr confirms that a collection has settled. Moves collected funds from the Modulr collection account into the organisation's Griffin DD holding account.

Forward: Griffin Holding → Agent Client Account

Triggered after the hold period has elapsed and the clawback reserve condition is satisfied. Moves cleared funds from the Griffin DD holding account into the agent's Griffin client account, making them available to the agent and landlord.

Account Balance Queries

The client can query the live balance of any Griffin holding account. This is used by the clawback reserve logic to determine whether sufficient funds are retained in the holding account before a forward is initiated.

Transaction History

Full transaction history for a Griffin account can be retrieved via the client. This supports:

Payment reconciliation
Audit trails for collected and forwarded amounts
Debugging failed or delayed payment legs

Asynchronous Payment Confirmation

Griffin processes payments asynchronously — payment leg creation returns immediately but confirmation arrives later via a webhook callback.

The service handles this by:

Recording the payment leg and its initial status at creation time.
Exposing a webhook endpoint that receives Griffin payment status events.
Updating the payment leg's status (e.g. pending → confirmed or failed) upon receipt of the callback.
Triggering downstream actions (e.g. initiating a forward after a sweep is confirmed) only once confirmation is received.

This ensures the fund flow is driven by confirmed state changes rather than optimistic assumptions.

Organisation Config

Griffin account identifiers are stored on the organisation config record:

Field	Description
`griffin_holding_account_id`	Griffin account ID for the organisation's DD holding account
`griffin_client_account_id`	Griffin account ID for the agent's client account (forwarding destination)

These values are set during onboarding and referenced automatically by the client throughout the fund flow.

Fund Flow Summary

Tenant Bank Account
       │
       │  BACS collection (via Modulr)
       ▼
Modulr Collection Account
       │
       │  Sweep payment leg (Griffin client)
       ▼
Griffin DD Holding Account
       │
       │  Hold period + clawback reserve check
       │
       │  Forward payment leg (Griffin client)
       ▼
Agent's Griffin Client Account

Error Handling

All Griffin API errors are caught and surfaced with typed error responses.
Failed payment legs are recorded with their failure reason.
Webhook delivery failures are handled gracefully — the service does not assume confirmation if no callback is received.