Griffin API Integration Client
Griffin API Integration Client
Version 1.0.10 ships a typed, server-side client for the Griffin Banking API. This client is the integration layer between the Direct Debit collection service and Griffin — handling all account-to-account payments, balance queries, transaction history, and inbound payment webhooks.
Overview
Griffin is the banking and fund-holding provider in the fund-flow pipeline. Collected funds are swept from the Modulr collection account into a Griffin DD holding account, held for the configurable clawback-protection period, then forwarded to the agent's Griffin client account. The Griffin API client facilitates every step of this process.
Features
Payment Initiation
The client exposes typed methods for initiating account-to-account payments on the Griffin platform:
- Sweep payment — Transfer funds from the Modulr collection account into the Griffin DD holding account once Modulr confirms collection.
- Forward payment — Transfer funds from the Griffin DD holding account into the agent's Griffin client account after the hold period has elapsed and the clawback reserve is satisfied.
All payment calls include an idempotency key (see below) to guard against duplicate transactions.
Account Balances
Query the real-time balance of any Griffin-managed account:
- DD holding account balance (used to assess clawback reserve status)
- Agent client account balance
Balances are returned in pence (GBP minor units) as typed response objects.
Transaction History
Retrieve paginated transaction history for a given Griffin account. This supports:
- Reconciliation of swept and forwarded amounts
- Audit trails for individual collection runs
- Reporting on fund movement over time
Payment Confirmation Webhooks
Griffin sends webhook events when a payment transitions to a terminal state (e.g. payment.completed, payment.failed). The client provides a webhook handler that:
- Verifies the incoming request signature (see HMAC Verification below)
- Parses and types the event payload
- Returns a normalised internal event object for downstream processing
Webhook-driven confirmation closes the loop on payment state — the hold-period scheduler and forward processor can react to confirmed events rather than polling.
Security
HMAC Webhook Verification
All inbound webhook requests from Griffin are verified using HMAC signature validation before any payload is processed. Requests with a missing, invalid, or tampered signature are rejected immediately and never reach application logic. This prevents spoofed payment confirmation events from being accepted.
The verification uses the shared secret configured in your Griffin webhook settings. See Environment Variables below.
Reliability
Idempotency Key Management
Every outbound payment request is issued with a unique idempotency key. If the same payment request is retried (e.g. due to a network timeout or worker restart), Griffin will return the original response rather than processing a second transaction. This ensures:
- No double-sweeps from Modulr to Griffin holding
- No double-forwards from Griffin holding to client account
- Safe retry behaviour in all failure scenarios
Error Normalisation
Griffin API errors (HTTP 4xx/5xx, network failures, unexpected response shapes) are caught at the client boundary and normalised into a consistent internal error type. This means:
- The rest of the service never handles Griffin-specific error formats directly
- Error handling logic is centralised and testable
- Logging and alerting receive uniform error objects regardless of the failure origin
Environment Variables
The Griffin API client requires the following environment variables to be configured:
| Variable | Description |
|---|---|
GRIFFIN_API_KEY | API key for authenticating requests to the Griffin API |
GRIFFIN_WEBHOOK_SECRET | Shared secret used to verify HMAC signatures on inbound Griffin webhooks |
GRIFFIN_BASE_URL | Base URL for the Griffin API (e.g. https://api.griffin.com) |
Related
- Changelog — v1.0.10
- Fund Flow Overview (see mission documentation)