Beancount Importer

The GoCardlessImporter class is a beangulp.Importer that fetches transactions from the GoCardless API and converts them into Beancount directives.

Configuration

The importer is configured using a YAML file. This file contains your credentials, cache settings, and account mappings.

# Credential injection (supported via environment variables)
secret_id: $GOCARDLESS_SECRET_ID
secret_key: $GOCARDLESS_SECRET_KEY

# Optional caching configuration
cache_options:
  cache_name: "gocardless"   # Default: "gocardless"
  backend: "sqlite"          # Default: "sqlite"
  expire_after: 3600         # Default: 0 (no cache)
  old_data_on_error: true    # Default: true

# Account configuration
accounts:
  - id: "ACCOUNT_UUID_FROM_CLI"
    asset_account: "Assets:Bank:MyAccount"

    # Optional settings
    transaction_types: ["booked", "pending"]  # Default: ["booked", "pending"]
    preferred_balance_type: "interimAvailable" # Default: checks expected, closingBooked, etc.

    # Metadata customization
    exclude_default_metadata: ["bookingDate"]
    metadata_fields:
        payee: "creditorName"
        cardScheme: "additionalDataStructured.cardInstrument.cardSchemeName"

Configuration Options

Global Settings:

  • secret_id: Your GoCardless Secret ID.

  • secret_key: Your GoCardless Secret Key.

  • cache_options: Dictionary of settings for requests-cache.

Account Settings:

  • id: The GoCardless Account ID (UUID). Retrieve this using the CLI (beancount-gocardless list_accounts).

  • asset_account: The Beancount account name to associate with these transactions (e.g., Assets:Banks:Checking).

  • transaction_types: List of transaction statuses to import. Options: booked, pending.

  • preferred_balance_type: The balance type to use for balance assertions. Common values: expected, interimAvailable, closingBooked.

  • exclude_default_metadata: List of default metadata keys to exclude (e.g., nordref, creditorName).

  • metadata_fields: Dictionary mapping custom metadata keys to fields in the GoCardless API response (supports dotted paths).

Usage

Create a Python script to run the import. This is standard for beangulp importers.

Basic Usage:

import beangulp
from beancount_gocardless import GoCardlessImporter

importer = GoCardlessImporter()

if __name__ == "__main__":
    ingest = beangulp.Ingest([importer])
    ingest()

With Smart Importer:

If you use smart_importer to predict payees and accounts:

import beangulp
from beancount_gocardless import GoCardlessImporter
from smart_importer import PredictPostings, PredictPayees

importer = GoCardlessImporter()

hooks = [
    PredictPostings().hook,
    PredictPayees().hook,
]

if __name__ == "__main__":
    ingest = beangulp.Ingest([importer], hooks=hooks)
    ingest()

Running the Import:

python my_import.py extract config.yaml

Extensibility

You can subclass GoCardlessImporter to customize behavior by overriding the following methods:

  • get_payee(transaction) — Return the payee string.

  • get_narration(transaction) — Return the narration string.

  • get_transaction_date(transaction) — Return the transaction date.

  • add_metadata(transaction, ...) — Return a dictionary of metadata key-value pairs.

  • create_transaction_entry(...) — Full control over Beancount entry creation.

Reference

class beancount_gocardless.importer.GoCardlessImporter[source]

Bases: Importer

GoCardless API importer for Beancount.

Fetches transactions from the GoCardless Bank Account Data API and converts them into Beancount directives.

Variables:

  • config – Configuration loaded from YAML.

  • _client – GoCardless API client instance.

DEFAULT_METADATA_FIELDS: Dict[str, str] = {'bookingDate': 'bookingDate', 'creditorName': 'creditorName', 'debtorName': 'debtorName', 'nordref': 'transactionId'}
NARRATION_SEPARATOR: str = ' '
__init__()[source]

Initialize the GoCardlessImporter.

Return type:

None

account(filepath)[source]

Return an empty string as account (derived from config instead).

Parameters:

filepath (str) – The path to the file (unused).

Return type:

str

Returns:

An empty string.

add_metadata(transaction, custom_metadata, account_config=None)[source]

Build the metadata dict for a Beancount transaction entry.

Merges default metadata fields, per-account custom fields from account_config, and any custom_metadata from the YAML config. Fields listed in account_config.exclude_default_metadata are removed.

This method can be overridden in subclasses to add extra metadata.

Parameters:

  • transaction (BankTransaction) – The source GoCardless transaction.

  • custom_metadata (Dict[str, Any]) – Static metadata dict from the account YAML config.

  • account_config (Optional[AccountConfig]) – Account-level configuration controlling field inclusion.

Return type:

Dict[str, Any]

Returns:

A dict of metadata key-value pairs to attach to the Beancount entry.

property client: GoCardlessClient

Lazily initialize and return the GoCardless API client.

Returns:

The initialized GoCardless API client.

Raises:

ValueError – If config is not loaded.

cmp = <beancount_gocardless.importer.ReferenceDuplicatesComparator object>
Parameters:

  • entry1 (beancount.core.data.Transaction)

  • entry2 (beancount.core.data.Transaction)

Return type:

bool

create_transaction_entry(transaction, status, asset_account, custom_metadata, account_config=None)[source]

Create a Beancount transaction entry from a GoCardless transaction.

Override in subclasses for full control over entry creation.

Parameters:

  • transaction (BankTransaction) – The GoCardless transaction data.

  • status (str) – Transaction status ("booked" or "pending").

  • asset_account (str) – The Beancount asset account string.

  • custom_metadata (Dict[str, Any]) – Static metadata dict from the account YAML config.

  • account_config (Optional[AccountConfig]) – Account-level configuration for metadata options.

Return type:

Optional[Transaction]

Returns:

A Beancount Transaction directive, or None if the transaction has no valid date or amount.

extract(filepath, existing=None)[source]

Extract Beancount entries from GoCardless transactions.

Duplicate detection is handled by the beangulp base class using cmp.

Parameters:

  • filepath (str) – The path to the YAML configuration file.

  • existing_entries – Previously extracted entries (used by the base class).

  • existing (beancount.core.data.Entries)

Return type:

Entries

Returns:

A list of Beancount transaction entries.

get_all_transactions(transactions_dict, types)[source]

Combine transactions of specified types and sort them by date.

Parameters:

  • transactions_dict (Dict[str, List[BankTransaction]]) – Transactions grouped by type.

  • types (List[str]) – Types to include.

Return type:

List[Tuple[BankTransaction, str]]

Returns:

Sorted list of (transaction, type) tuples.

get_narration(transaction)[source]

Extract the narration from a transaction.

This method can be overridden in subclasses to customize narration extraction.

Parameters:

transaction (BankTransaction) – The transaction data from the API.

Return type:

str

Returns:

The extracted narration.

get_payee(transaction)[source]

Extract the payee from a transaction.

Override in subclasses to customize payee extraction. The default implementation returns an empty string.

Parameters:

transaction (BankTransaction) – The transaction data from the API.

Return type:

str

Returns:

The extracted payee string (empty by default).

get_transaction_date(transaction)[source]

Extract the transaction date. Prefers value_date, falls back to booking_date.

This method can be overridden in subclasses to customize date extraction.

Parameters:

transaction (BankTransaction) – The transaction data from the API.

Return type:

Optional[date]

Returns:

The extracted transaction date, or None if no date is found.

get_transaction_status(transaction, status, metakv, tx_amount, asset_account)[source]

Determine the Beancount flag for a transaction.

Override in subclasses to customize flag assignment. The default returns FLAG_OKAY for booked transactions and FLAG_WARNING for pending.

Parameters:

  • transaction (BankTransaction) – The transaction data from the API.

  • status (str) – Transaction status ("booked" or "pending").

  • metakv (Dict[str, Any]) – Transaction metadata dict.

  • tx_amount (Amount) – Transaction amount.

  • asset_account (str) – The Beancount asset account string.

Return type:

str

Returns:

A Beancount flag character.

identify(filepath)[source]

Identify if the given file is a GoCardless configuration file.

Parameters:

filepath (str) – The path to the file.

Return type:

bool

Returns:

True if the file is a GoCardless configuration file.

load_config(filepath)[source]

Load configuration from the specified YAML file.

Parameters:

filepath (str) – The path to the YAML configuration file.

Return type:

Optional[GoCardlessConfig]

Returns:

The loaded configuration. Also sets self.config.

class beancount_gocardless.importer.ReferenceDuplicatesComparator(refs=['ref'])[source]

Bases: object

Compare two Beancount transactions for duplicate detection.

Two entries are considered duplicates if they share at least one common value among the specified metadata reference keys.

Parameters:

refs (List[str]) – Metadata keys to compare (default: ["ref"]).

__init__(refs=['ref'])[source]
Parameters:

refs (List[str])

Return type:

None