Modules
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.
Account and balance operations: listing accounts, fetching balances, and Account Holder Verification (AHV / Confirmation-of-Payee style checks across supported schemes).
An OAuth2 JWT access token issued by Banking Circle's authorization endpoint, with the metadata needed to decide when to refresh it.
Caches a Banking Circle OAuth2 JWT per configured client and refreshes it transparently, following Banking Circle's documented guidance
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.
Convenience helpers for building the :answers list passed to
BankingCircle.Cases.submit_rfi_answers/3.
Validated runtime configuration for a Banking Circle client instance.
Direct Debit Collections: initiating a collection against a pre-authorized mandate you (the creditor) hold on the debtor's account.
Resolves Banking Circle Connect's environment-specific base URLs.
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.
Foreign exchange: market-order trading, Request-for-Quote (RFQ), indicative rates, held rates, and trade/exposure lookups.
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).
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.
Attaches an Idempotency-Key header to a request, either from a caller
supplied value or a generated UUIDv4.
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).
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.
Single and bulk payment initiation, status tracking, cancellation, and lookup, per the Payment Lifecycle documentation.
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).
Validates a batch of payment rows destined for POST /payments/bulks
and renders them into the CSV format that endpoint expects.
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).
Standardized :telemetry events emitted by this client.
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).
Decrypts and verifies incoming Banking Circle webhook payloads.
Manages webhook subscriptions (create/list/activate/deactivate/remove) via the notification self-service API.