# `BankingCircle`
[🔗](https://github.com/iamkanishka/banking_circle/blob/main/lib/banking_circle.ex#L1)

A production-grade Elixir client for the [Banking Circle Connect
API](https://docs.bankingcircleconnect.com) — 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)

# `start_client`

```elixir
@spec start_client(
  atom(),
  keyword()
) :: DynamicSupervisor.on_start_child()
```

Starts a `TokenServer` for the given client name under the application's
`DynamicSupervisor`.

Called automatically at boot for `:default` and any `:entities` found in
application config; call it directly only for clients configured purely
at runtime.

# `stop_client`

```elixir
@spec stop_client(atom()) :: :ok | {:error, :not_found}
```

Stops the `TokenServer` for the given client name, if running.

---

*Consult [api-reference.md](api-reference.md) for complete listing*