API Client

The GoCardlessClient provides a typed interface to the GoCardless Bank Account Data API.

Features

Requests and responses use Pydantic models for type safety.
API responses can be cached locally via requests-cache (SQLite backend by default).
Access tokens are acquired and refreshed automatically.
Response headers (e.g. Cache-Control) are stripped to prevent them from overriding requests-cache behavior, which would cause unnecessary re-fetching of cached data.

Usage

Initialize the client with your credentials:

from beancount_gocardless import GoCardlessClient

client = GoCardlessClient(
    secret_id="your-secret-id",
    secret_key="your-secret-key",
    cache_options={
        "cache_name": "gocardless_cache",
        "expire_after": 3600  # 1 hour
    }
)

# List banks in Great Britain
banks = client.list_banks("GB")

# Get all connected accounts
accounts = client.get_all_accounts()

Reference

GoCardless Bank Account Data API client.

Wraps the GoCardless REST API with Pydantic models and SQLite-backed response caching (via requests-cache).

class beancount_gocardless.client.CacheOptions[source]

Bases: TypedDict

backend: str

cache_control: bool

cache_name: str

expire_after: int

match_headers: bool

old_data_on_error: bool

class beancount_gocardless.client.GoCardlessClient(secret_id, secret_key, cache_options=None)[source]

Bases: object

GoCardless Bank Account Data API client.

Wraps the GoCardless (formerly Nordigen) REST API with typed return values (Pydantic models), optional SQLite-backed response caching, and automatic JWT token acquisition/refresh.

Parameters:

secret_id (str) – GoCardless API secret ID.
secret_key (str) – GoCardless API secret key.
cache_options (Optional[CacheOptions]) – Optional dict of keyword arguments forwarded to requests_cache.CachedSession. If None, default caching settings are used (SQLite backend, no expiry).

BASE_URL = 'https://bankaccountdata.gocardless.com/api/v2'

__init__(secret_id, secret_key, cache_options=None)[source]

Parameters:

secret_id (str)
secret_key (str)
cache_options (CacheOptions | None)

accept_agreement(agreement_id, user_agent, ip)[source]

Accept an end-user agreement.

Return type:

Dict[str, Any]

Parameters:

agreement_id (str)
user_agent (str)
ip (str)

check_cache_status(method, url, params=None, data=None)[source]

Check whether a cached response exists for the given request.

Parameters:

method (str) – HTTP method (e.g. "GET").
url (str) – Full request URL.
params – Optional query parameters.
data – Optional request body data.

Return type:

dict

Returns:

Dict with keys key_exists (bool), is_expired (bool or None), and cache_key (str).

create_agreement(institution_id, max_historical_days, access_valid_for_days, access_scope, **kwargs)[source]

Create an end-user agreement for a given institution.

Parameters:

institution_id (str) – ID of the banking institution.
max_historical_days (int) – Maximum number of days of transaction history.
access_valid_for_days (int) – Number of days the access is valid.
access_scope (List[str]) – List of access scopes (e.g. ["balances", "details", "transactions"]).
**kwargs – Additional fields forwarded to the API.

Return type:

EndUserAgreement

create_bank_link(reference, bank_id, redirect_url='http://localhost')[source]

Create a bank authorization link and return the URL.

Returns None if a requisition with the same reference already exists.

Return type:

Optional[str]

Parameters:

reference (str)
bank_id (str)
redirect_url (str)

create_requisition(redirect, institution_id, reference, **kwargs)[source]

Create a new requisition (bank authorization request).

Parameters:

redirect (str) – URL the user is redirected to after authorization.
institution_id (str) – ID of the banking institution.
reference (str) – A unique reference string for this requisition.
**kwargs – Additional fields forwarded to the API.

Return type:

Requisition

delete(endpoint)[source]

Send a DELETE request and return the JSON response body.

Return type:: Dict[str, Any]
Parameters:: endpoint (str)

delete_requisition(requisition_id)[source]

Delete a requisition by its ID.

Return type:: Dict[str, Any]
Parameters:: requisition_id (str)

find_requisition_by_reference(reference)[source]

Find a requisition by its reference string, or return None.

Return type:: Optional[Requisition]
Parameters:: reference (str)

get(endpoint, params=None)[source]

Send a GET request and return the JSON response body.

Return type:

Dict[str, Any]

Parameters:

endpoint (str)
params (Dict | None)

get_access_token()[source]

Obtain a new JWT access token. Usually handled internally by the client.

Return type:: SpectacularJWTObtain

get_account(account_id)[source]

Retrieve metadata for a single account.

Return type:: Account
Parameters:: account_id (str)

get_account_balances(account_id)[source]

Retrieve balances for a single account.

Return type:: AccountBalance
Parameters:: account_id (str)

get_account_details(account_id)[source]

Retrieve detailed information for a single account.

Return type:: AccountDetail
Parameters:: account_id (str)

get_account_transactions(account_id, days_back=180)[source]

Retrieve transactions for an account within a date range.

Follows pagination links to fetch all available pages, up to MAX_PAGINATION_PAGES pages to prevent infinite loops.

Parameters:

account_id (str) – GoCardless account UUID.
days_back (int) – Number of days of history to fetch (default 180).

Return type:

AccountTransactions

Returns:

AccountTransactions with all booked and pending transactions.

get_agreement(agreement_id)[source]

Retrieve a single end-user agreement by its ID.

Return type:: EndUserAgreement
Parameters:: agreement_id (str)

get_agreements()[source]

List all end-user agreements.

Return type:: List[EndUserAgreement]

get_agreements_paginated(limit=None, offset=None)[source]

List end-user agreements with pagination support.

Return type:

PaginatedEndUserAgreementList

Parameters:

limit (int | None)
offset (int | None)

get_all_accounts()[source]

Collect all accounts across all requisitions, with expiry metadata.

Return type:: List[AccountInfo]

get_institution(institution_id)[source]

Retrieve a single institution by its ID.

Return type:: Institution
Parameters:: institution_id (str)

get_institutions(country=None)[source]

List available banking institutions, optionally filtered by country code.

Return type:: List[Institution]
Parameters:: country (str | None)

get_integration(integration_id)[source]

Retrieve a single integration by its ID.

Return type:: Integration
Parameters:: integration_id (str)

get_integrations()[source]

List all integrations.

Return type:: List[Integration]

get_requisition(requisition_id)[source]

Retrieve a single requisition by its ID.

Return type:: Requisition
Parameters:: requisition_id (str)

get_requisitions()[source]

List all requisitions.

Return type:: List[Requisition]

get_requisitions_paginated(limit=None, offset=None)[source]

List requisitions with pagination support.

Return type:

PaginatedRequisitionList

Parameters:

limit (int | None)
offset (int | None)

get_token()[source]: Fetch a new API access token using credentials.

list_accounts()[source]

Alias for get_all_accounts().

Return type:: List[AccountInfo]

list_banks(country=None)[source]

Return a list of bank names, optionally filtered by country code.

Return type:: List[str]
Parameters:: country (str | None)

post(endpoint, data=None)[source]

Send a POST request and return the JSON response body.

Return type:

Dict[str, Any]

Parameters:

endpoint (str)
data (Dict | None)

reconfirm_agreement(agreement_id, user_agent, ip)[source]

Reconfirm an end-user agreement.

Return type:

ReconfirmationRetrieve

Parameters:

agreement_id (str)
user_agent (str)
ip (str)

refresh_access_token(refresh_token)[source]

Refresh an existing JWT access token.

Return type:: SpectacularJWTRefresh
Parameters:: refresh_token (str)

property token: str: Return a valid access token, refreshing if expired or missing.

beancount_gocardless.client.strip_headers_hook(response, *args, **kwargs)[source]

Strip response headers that override requests_cache behavior.

Headers like Cache-Control cause requests_cache to re-fetch data that is already cached locally. Removing them lets the custom cache logic take precedence and avoids unnecessary network requests.