HBCI / FinTS (German Banking)

DieselEngine provides access to the hbci4java library for German online banking via the HBCI and FinTS protocols. Use it for account inquiries, balance checks, transaction history, and SEPA transfers.

Getting the Service

const hbci = diesel.getHBCIService();

How It Works

HBCI/FinTS is a protocol used by German banks for online banking. The workflow involves:

1. Initialize the hbci4java kernel with properties and a callback
2. Look up bank info by BLZ (Bankleitzahl)
3. Create a passport (stores bank and user parameters, encrypted on disk)
4. Create a handler (session) for the passport
5. Create and execute jobs (balance inquiry, transaction list, transfers)
6. Shut down when done

The HBCIService provides convenience factory methods for the most common operations. Full flexibility is available via Java.type() access to the underlying hbci4java library.

Thread Safety

hbci4java uses ThreadGroup-based configuration isolation. Each script execution in DieselEngine runs in its own context, so concurrent banking sessions are naturally isolated. However, a single HBCIHandler instance is not thread-safe -- each session needs its own handler + passport.

Initialization

hbci.init(properties, callback)

Initialize the HBCI4Java subsystem. Must be called once before any other HBCI operations.

• Parameters:
  • properties: Properties — kernel parameters (may be empty; hbci4java has sensible defaults)
  • callback: HBCICallback — callback handler for PIN/TAN interaction

const HBCICallback = Java.type('org.kapott.hbci.callback.AbstractHBCICallback');
const Properties = Java.type('java.util.Properties');

class MyCallback extends HBCICallback {
  NEED_PIN_TAN(sysType, tanMode, tanModeName, serverName, serverDesc, tanData) {
    // Return the TAN (one-time password) from your TAN generator
    return "12345678";
  }

  NEED_PASSPHRASE_LOAD(saveFile) {
    // Return the passphrase to decrypt the passport file
    return "my-secret-passphrase";
  }

  NEED_PASSPHRASE_SAVE(saveFile) {
    // Return the passphrase to encrypt the passport file
    return "my-secret-passphrase";
  }
}

hbci.init(new Properties(), new MyCallback());

hbci.isInitialized()

Check whether HBCIUtils.init() has been called in the current thread group.

• Returns: boolean

if (!hbci.isInitialized()) {
  hbci.init(new Properties(), new MyCallback());
}

Bank Info

hbci.getBankInfo(blz)

Look up bank information by BLZ (Bankleitzahl). Returns the bank's name, PIN/TAN server address, supported HBCI version, etc.

• Parameters: blz: string — 8-digit German bank code
• Returns: BankInfo | null

const bankInfo = hbci.getBankInfo("10000000"); // Deutsche Bank
console.log("Bank:", bankInfo.getBankname());
console.log("HBCI version:", bankInfo.getHbcidVersion());

Passport

hbci.createPinTanPassport(passportFile)

Create a PinTan passport backed by a file on disk. The passport stores bank parameters (BPD), user parameters (UPD), and server addresses. It is encrypted with a passphrase provided via the callback.

• Parameters: passportFile: File — file path to store/load passport data
• Returns: HBCIPassport

const File = Java.type('java.io.File');
const passportFile = new File("/data/diesel/banking/passport.p3");
const passport = hbci.createPinTanPassport(passportFile);

Handler (Session)

hbci.createHandler(hbciVersion, passport)

Create an HBCI handler (session) for the given passport. Opens a connection to the bank, fetches BPD/UPD if needed, and prepares the handler for creating and executing jobs.

• Parameters:
  • hbciVersion: string — HBCI/FinTS version (e.g., "300" for FinTS 3.0)
  • passport: HBCIPassport — authenticated passport
• Returns: HBCIHandler

const handler = hbci.createHandler("300", passport);

Creating and Executing Jobs

Once you have a handler, you can create and execute banking jobs using the hbci4java API directly:

const HBCIUtils = Java.type('org.kapott.hbci.manager.HBCIUtils');
const JobNoStatement = Java.type('org.kapott.hbci.jobs.JobNoStatement');
const JobAmtsreq = Java.type('org.kapott.hbci.jobs.JobAmtsreq');

// Create a balance inquiry job
const accounts = handler.getAccounts();
const account = accounts.get(0);

const balanceJob = new JobAmtsreq(handler, account);
handler.addJob(balanceJob);

// Execute all jobs
handler.doTransactions();

// Get the result
const balance = balanceJob.getSaldo();
console.log("Balance:", balance / 100, "EUR");

Common Job Types

Job Class	Purpose
JobNoStatement	Get account statement (transactions)
JobAmtsreq	Get account balance
JobSepaLasting	SEPA direct debit mandate
JobSepaUeberw	SEPA credit transfer
JobZaehlerstatus	Get meter readings (smart home)

Shutdown

hbci.done()

Shut down the HBCI4Java subsystem for the current thread group. Call this when done with all HBCI operations to free resources.

hbci.done();

Common Patterns

Full Account Inquiry

// Initialize
hbci.init(new Properties(), new MyCallback());

// Load passport
const passportFile = new java.io.File("/data/diesel/banking/passport.p3");
const passport = hbci.createPinTanPassport(passportFile);

// Create handler
const handler = hbci.createHandler("300", passport);

// Get accounts
const accounts = handler.getAccounts();
for (const account of accounts) {
  console.log("Account:", account.getIban());

  // Balance inquiry
  const balanceJob = new JobAmtsreq(handler, account);
  handler.addJob(balanceJob);
}

// Execute
handler.doTransactions();

// Get results
for (const account of accounts) {
  const job = handler.getJobForAccount(account, JobAmtsreq.class);
  if (job) {
    const balance = job.getSaldo();
    console.log("Balance:", balance / 100, "EUR");
  }
}

// Clean up
hbci.done();

Transaction History

const statementJob = new JobNoStatement(handler, account);
statementJob.setDatVon(java.time.LocalDate.now().minusMonths(1));
statementJob.setDatBis(java.time.LocalDate.now());
handler.addJob(statementJob);

handler.doTransactions();

const transactions = statementJob.getVorgaenge();
for (const tx of transactions) {
  console.log(tx.getDatum(), tx.getBetrag() / 100, tx.getText());
}

API Reference

Method	Description
hbci.init(properties, callback)	Initialize HBCI4Java subsystem
hbci.isInitialized()	Check if initialized
hbci.getBankInfo(blz)	Look up bank by BLZ
hbci.createPinTanPassport(file)	Create passport from file
hbci.createHandler(version, passport)	Create HBCI handler (session)
hbci.done()	Shut down HBCI4Java