# banking_circle v1.0.0 - Table of Contents

> A complete, production-grade Elixir client for the Banking Circle Connect API —
payments (single & bulk), accounts, webhooks (AES-256-GCM verified), OAuth2/JWT
auth with automatic token refresh, idempotency, retries, and telemetry.

## Pages

- [BankingCircle](readme.md)
- [Changelog](changelog.md)

## Modules

- [BankingCircle](BankingCircle.md): 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.
- [BankingCircle.Config](BankingCircle.Config.md): Validated runtime configuration for a Banking Circle client instance.
- [BankingCircle.Environment](BankingCircle.Environment.md): Resolves Banking Circle Connect's environment-specific base URLs.
- [BankingCircle.Telemetry](BankingCircle.Telemetry.md): Standardized `:telemetry` events emitted by this client.
- [BankingCircle.Webhook.Verifier](BankingCircle.Webhook.Verifier.md): Decrypts and verifies incoming Banking Circle webhook payloads.

- Auth
  - [BankingCircle.Auth.Token](BankingCircle.Auth.Token.md): An OAuth2 JWT access token issued by Banking Circle's authorization
endpoint, with the metadata needed to decide when to refresh it.
  - [BankingCircle.Auth.TokenServer](BankingCircle.Auth.TokenServer.md): Caches a Banking Circle OAuth2 JWT per configured client and refreshes it
transparently, following Banking Circle's documented guidance

- HTTP
  - [BankingCircle.HTTP.Client](BankingCircle.HTTP.Client.md): Builds the shared `Req` request pipeline used by every resource module
(`BankingCircle.Payments`, `BankingCircle.Accounts`, ...), and exposes
`request/2` as the single choke point through which all API traffic
flows — this is where auth injection, retries, telemetry, and error
normalization all compose.

  - [BankingCircle.HTTP.Middleware.Idempotency](BankingCircle.HTTP.Middleware.Idempotency.md): Attaches an `Idempotency-Key` header to a request, either from a caller
supplied value or a generated UUIDv4.
  - [BankingCircle.HTTP.Middleware.Retry](BankingCircle.HTTP.Middleware.Retry.md): Configures Req's built-in retry mechanism with Banking-Circle-appropriate
policy: capped exponential backoff with full jitter, honoring a
server-provided `Retry-After` when present (notably on 429s from the auth
and payment endpoints).

- Resources
  - [BankingCircle.Accounts](BankingCircle.Accounts.md): Account and balance operations: listing accounts, fetching balances,
and Account Holder Verification (AHV / Confirmation-of-Payee style
checks across supported schemes).

  - [BankingCircle.Cases](BankingCircle.Cases.md): Case Management: Banking Circle raises a **Case** when it needs
something from you — most commonly an RFI (Request for Information,
usually a sanctions-screening hold on a payment) or a Recall Case (the
counterparty bank asking you to return a payment they sent you). A case
stays `"OPEN"` until you respond or a deadline passes, and not
responding has real consequences (payment delay/rejection, account
restriction), so treat `list_cases/2` (or the case-opened webhook) as
something worth polling/handling promptly rather than best-effort.
  - [BankingCircle.Cases.RFI](BankingCircle.Cases.RFI.md): Convenience helpers for building the `:answers` list passed to
`BankingCircle.Cases.submit_rfi_answers/3`.

  - [BankingCircle.DirectDebit](BankingCircle.DirectDebit.md): Direct Debit Collections: initiating a collection against a
pre-authorized mandate you (the creditor) hold on the debtor's account.
  - [BankingCircle.FX](BankingCircle.FX.md): Foreign exchange: market-order trading, Request-for-Quote (RFQ),
indicative rates, held rates, and trade/exposure lookups.
  - [BankingCircle.FX.Stream](BankingCircle.FX.Stream.md): Streaming FX quotes and Market Order execution over Banking Circle's FX
WebSocket — the "sophisticated FX workflows" path Banking Circle's docs
explicitly say to reach for only after you've outgrown the REST APIs
(`BankingCircle.FX`).
  - [BankingCircle.ISO20022](BankingCircle.ISO20022.md): Payment initiation via raw ISO20022 XML messages, for shops already
standardized on pain.001 (customer credit transfer initiation) or
pacs.008 (FI-to-FI credit transfer) rather than Banking Circle's JSON
payment shape.
  - [BankingCircle.Payments](BankingCircle.Payments.md): Single and bulk payment initiation, status tracking, cancellation, and
lookup, per the Payment Lifecycle documentation.
  - [BankingCircle.Reporting](BankingCircle.Reporting.md): Asynchronous report generation: request a report, poll its status, then
download it once ready — the three-step flow Banking Circle uses for
reports too large to return synchronously (reconciliation, account
activity, rejections, bank statements, camt.053, etc).
  - [BankingCircle.VirtualAccounts](BankingCircle.VirtualAccounts.md): Virtual Accounts (VIBANs): externally addressable IBANs that route to
one or more physical Master Accounts rather than holding funds
themselves. Used for account reconciliation (one VIBAN per seller),
treasury consolidation, and third-party account services (POBO/COBO —
paying/collecting on behalf of your customer, under their own name).
  - [BankingCircle.Webhooks](BankingCircle.Webhooks.md): Manages webhook subscriptions (create/list/activate/deactivate/remove)
via the notification self-service API.

- Schemas
  - [BankingCircle.Schemas.BulkPayment](BankingCircle.Schemas.BulkPayment.md): Validates a batch of payment rows destined for `POST /payments/bulks`
and renders them into the CSV format that endpoint expects.
  - [BankingCircle.Schemas.Payment](BankingCircle.Schemas.Payment.md): Validates and casts a single-payment request before it's sent to
`POST /payments/singles`, using an Ecto embedded schema purely as a
typed-casting + changeset-validation tool (no database involved).

- Errors
  - [BankingCircle.Error](BankingCircle.Error.md): Canonical error representation for every failure mode this client can
surface: transport failures, HTTP 4xx/5xx responses (in either of Banking
Circle's two documented error body shapes), auth failures, and
client-side validation errors raised before a request is ever sent.