A production-grade Elixir client for the Banking Circle Connect API — payments (single & bulk), accounts, and webhooks, with OAuth2/JWT auth (auto-refreshed, single-flight), idempotency, retries with jittered backoff, and :telemetry instrumentation.

See the moduledocs on BankingCircle.Payments, BankingCircle.Accounts, and BankingCircle.Webhooks for the actual API surface. This module is the entry point for client lifecycle management.

Quick start

# config/runtime.exs
config :banking_circle, BankingCircle,
  environment: :sandbox,
  username: {:system, "BC_USERNAME"},
  password: {:system, "BC_PASSWORD"},
  certificate_thumbprint: {:system, "BC_CERT_THUMBPRINT"},
  client_cert_path: {:system, "BC_CLIENT_CERT_PATH"},
  client_key_path: {:system, "BC_CLIENT_KEY_PATH"}

With that in place, the :default client starts automatically under the application supervisor:

{:ok, payment} = BankingCircle.Payments.create_single(%{
  debtor_account_id: "acc_123",
  amount: Decimal.new("100.50"),
  currency: "EUR",
  creditor_name: "Jane Doe",
  creditor_iban: "DE89370400440532013000",
  transaction_reference: "INV-2026-001"
})

Multiple clients (e.g. one per legal entity)

config :banking_circle, :entities,
  eu_entity: [environment: :production, username: {:system, "BC_EU_USER"}, ...],
  uk_entity: [environment: :production, username: {:system, "BC_UK_USER"}, ...]

BankingCircle.Payments.create_single(attrs, :eu_entity)

Runtime-only clients

For multi-tenant systems where the client set isn't known at compile time, start (and stop) clients dynamically:

{:ok, _pid} = BankingCircle.start_client(:tenant_42, environment: :production, username: ..., ...)
:ok = BankingCircle.stop_client(:tenant_42)