comdirect API Go Client

Go wrapper library for the comdirect API.

Installation

go get github.com/anytoe/comdirect-api-golang

Usage

Once authenticated, you can use the client to build your own business logic on top of the comdirect API:

package main

import (
    "bufio"
    "context"
    "fmt"
    "log"
    "os"
    "strings"

    "github.com/anytoe/comdirect-api-golang/pkg/comdirect"
)

func main() {
    client := comdirect.NewClient(&comdirect.Config{
        TokenStore: comdirect.NewFileTokenStore(""),
    })

    ctx := context.Background()

    if err := client.Authenticate(ctx, comdirect.AuthConfig{
        ClientID:     os.Getenv("COMDIRECT_CLIENT_ID"),
        ClientSecret: os.Getenv("COMDIRECT_CLIENT_SECRET"),
        Username:     os.Getenv("COMDIRECT_USERNAME"),
        Password:     os.Getenv("COMDIRECT_PASSWORD"),
    }, func(challenge string) (string, error) {
        fmt.Println(challenge)
        reader := bufio.NewReader(os.Stdin)
        tan, _ := reader.ReadString('\n')
        return strings.TrimSpace(tan), nil
    }); err != nil {
        log.Fatal(err)
    }

    // --- Your business logic here ---
    accounts, err := client.ListAccounts(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, a := range accounts {
        fmt.Printf("%s (%s): %.2f %s\n", a.DisplayID, a.IBAN, a.Balance.Value, a.Balance.Currency)
    }
}

Examples

The examples/ directory contains runnable programs that demonstrate each API feature. Run any example with:

source .env  # or export the required environment variables
go run ./examples/<name>/

listaccounts

Lists all accounts with their IBAN, type, and current balance.

go run ./examples/listaccounts/

Found 2 accounts:
  - 1234567890 (DE12 1234 5678 1234 5678 00): CHECKING 1234.56 EUR
  - 9876543210 (DE98 9999 5678 1234 5678 00): SAVINGS   567.89 EUR

documents

Fetches the most recent documents from the comdirect mailbox. Unread documents are marked with *.

go run ./examples/documents/

--- Documents ---
  * 2025-12-17  text/html       Wissenswertes zum Jahresende
  * 2025-12-15  text/html       Änderung der Kundeninformation zum Wertpapiergeschäft
  * 2026-02-04  application/pdf  Finanzreport Nr. 01 per 02.02.2026
    2026-01-07  text/html       Warnung: Betrug beim mobilen Bezahlen

4 document(s) shown (use PagingFirst/PagingCount to page through more)

reports

Shows balances across all products (accounts, cards, depots, loans, savings).

go run ./examples/reports/

--- All Product Balances ---
  ACCOUNT   1234567890             1234.56 EUR
  SAVINGS   9876543210              567.89 EUR
  DEPOT     D12345678               299.10 EUR

transactions

Lists accounts, picks the first one with a non-zero balance, and shows its recent transactions.

go run ./examples/transactions/

--- Accounts ---
  1234567890  DE12 3456 7890 1234 5678 90  CHECKING   1234.56 EUR

--- Transactions for account 1234567890 ---
  2026-02-03    -49.99 EUR  -                    -> REWE Markt GmbH       Einkauf REWE Markt
  2026-02-01  +1999.00 EUR  Arbeitgeber GmbH     -> -                     Gehalt Februar
  2026-01-28    -29.90 EUR  -                    -> Deutsche Telekom AG   Mobilfunk Januar

Authentication Flow

The Authenticate call performs a 5-step OAuth2 flow required by comdirect:

1. Password grant — exchanges credentials for an initial token
2. Get session — retrieves the session ID
3. Validate session — triggers a TAN challenge (photoTAN / pushTAN)
4. Submit TAN — confirms the challenge
5. Secondary grant — exchanges the validated token for a final access token

The TANCallback function is called at step 3 to prompt the user.

Environment Variables

COMDIRECT_CLIENT_ID
COMDIRECT_CLIENT_SECRET
COMDIRECT_USERNAME
COMDIRECT_PASSWORD

API credentials can be obtained from the comdirect developer portal.

Token Storage

The library provides two TokenStore implementations:

• InMemoryTokenStore — default if none is provided. Token is lost when the process exits.
• FileTokenStore — persists the token to disk (~/.comdirect/token.json by default). Survives restarts.

// Explicit file store
client := comdirect.NewClient(&comdirect.Config{
    TokenStore: comdirect.NewFileTokenStore(""),
})

// Implicit in-memory store (default)
client := comdirect.NewClient(&comdirect.Config{})

When a token expires, API calls return an error — re-authentication must be triggered manually by calling Authenticate again.

Note: The API returns a refresh token which is stored but not yet used. Token refresh without TAN is not yet implemented.

Contributing

This project is primarily built for personal use, but contributions are welcome. Feel free to open issues or pull requests.

API Coverage

Banking

Method	Description
ListAccounts(ctx)	All accounts with balances
GetAccountBalance(ctx, accountID)	Balance for a specific account
ListAccountTransactions(ctx, accountID, filter)	Transactions with optional direction/state filter

Reports

Method	Description
GetAllBalances(ctx)	Balances for all products (accounts, cards, depots, loans, savings)

Documents

Method	Description
ListDocuments(ctx, filter)	Paginated list of mailbox documents