banking_circle

# BankingCircle

[![Hex.pm](https://img.shields.io/hexpm/v/banking_circle.svg)](https://hex.pm/packages/banking_circle)
[![Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/banking_circle)

A production-grade Elixir client for the [Banking Circle Connect
API](https://docs.bankingcircleconnect.com): cross-border payments (single
& bulk), accounts, and webhooks — with OAuth2/JWT auth (auto-refreshed,
single-flighted), client-side request validation, safe retries with
jittered backoff, idempotency support, and `:telemetry` instrumentation.

## Scope of this release

This package implements the full documented API surface: **Authentication**,
**Payments** (single & bulk, plus recalls and traces), **Accounts** (basic
operations, bookings/ledger, + AHV), **Virtual Accounts** (VIBANs —
listing, ordering, POBO/COBO customer/UBO details, closure lifecycle),
**Webhooks** (subscription management + AES-256-GCM payload verification),
**FX** (market-order trading, RFQ, indicative rates, held rates, trade
history/exposure, plus a WebSocket streaming client for live quotes and
Market Order execution), **Reporting** (both the async request → poll →
download flow, and the synchronous Reconciliation Report endpoint),
**Case Management** (RFI and Recall cases, including attachment upload
and answer submission), **Direct Debit Collections** (mandate-based
collection initiation, the one endpoint with documented idempotency-key
support), **Correspondent and Agency Banking** (the
`fi-to-fi-customer-credit-transfer-initiation` JSON endpoint), **ISO20022**
message transport (pain.001/pacs.008/camt.053 — see the scope note on
`BankingCircle.ISO20022` below), **Error handling**, **Idempotency**, and
**Rate limiting / retry**.

**Deliberately out of scope: Correspondent/Agency Banking via Swift.**
That integration path runs over the SWIFT FIN network itself (MT101/MT103
message exchange, BIC-to-BIC, via your Swift service bureau or direct
connection) — it isn't a Banking Circle Connect HTTP endpoint at all, so
there's nothing for an HTTP client library to wrap. If your integration
needs this, it's a separate SWIFT connectivity project, not something
`banking_circle` can extend into.

**Genuinely not implemented: Aliases (PayID, etc.).** Banking Circle's
docs describe this feature but I couldn't find its REST endpoint paths
and payload shapes documented anywhere I could search — rather than
invent plausible-looking endpoints for a payment-routing feature (where a
wrong guess is actively dangerous, not just inconvenient), I've left it
out. If you have API reference access to the Aliases endpoints, that's
a straightforward addition following the same pattern as every other
module here.

**Narrower scope notes, not full gaps:**
- `BankingCircle.VirtualAccounts.order/2`'s endpoint path is inferred
  from consistent terminology in the docs, not confirmed against the API
  reference directly — see its moduledoc before relying on it. Every
  other function in that module (list, close, close-status,
  add-customer-details, customer-details-status) is confirmed.
- `BankingCircle.ISO20022` is a transport layer (posts XML you supply to
  the right endpoint with the right content type) — it does not build or
  validate pain.001/pacs.008/camt.053 XML documents for you. See its
  moduledoc.
- `BankingCircle.FX.Stream` (WebSocket streaming quotes) is built on
  `WebSockex` rather than `Req`, has a genuinely different
  connection-lifecycle shape from the rest of this library, and — per its
  moduledoc — has had less real-world exercise than the REST modules.
  Verify reconnect/token-refresh behavior against your own sandbox before
  relying on it for production execution.

**Note on network verification:** every module here has been written and
tested against a hand-built harness (Bypass fake servers standing in for
Banking Circle's endpoints) rather than against Banking Circle's actual
sandbox — some endpoint paths, request/response field names, and the
webhook checksum construction should be confirmed against your own
sandbox account before going to production. Wherever the docs left a
detail ambiguous, the code says so in a comment (see especially
`BankingCircle.Webhook.Verifier` and the mTLS `connect_options` in
`BankingCircle.Auth.TokenServer`).

## Installation

```elixir
def deps do
  [
    {:banking_circle, "~> 1.0.0"}
  ]
end
```

## Configuration

Banking Circle uses **entirely separate hosts, credentials, and client
certificates** for sandbox vs. production — mixing them up is the most
common integration mistake, so `BankingCircle.Config` validates all of
this at boot rather than at first request.

```elixir
# config/runtime.exs
import Config

config :banking_circle, BankingCircle,
  environment: :sandbox, # or :production
  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"},
  request_timeout_ms: 15_000,
  max_retries: 3
```

With that in place, add nothing else — BankingCircle.Application starts
a supervised `TokenServer` for the `:default` client automatically.

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

```elixir
config :banking_circle, :entities,
  eu_entity: [
    environment: :production,
    username: {:system, "BC_EU_USERNAME"},
    password: {:system, "BC_EU_PASSWORD"},
    certificate_thumbprint: {:system, "BC_EU_CERT_THUMBPRINT"}
  ],
  uk_entity: [
    environment: :production,
    username: {:system, "BC_UK_USERNAME"},
    password: {:system, "BC_UK_PASSWORD"},
    certificate_thumbprint: {:system, "BC_UK_CERT_THUMBPRINT"}
  ]
```

```elixir
BankingCircle.Payments.create_single(attrs, :eu_entity)
```

### Runtime-only clients (multi-tenant)

```elixir
{:ok, _pid} =
  BankingCircle.start_client(:tenant_42,
    environment: :production,
    username: tenant.bc_username,
    password: tenant.bc_password,
    certificate_thumbprint: tenant.bc_cert_thumbprint
  )

BankingCircle.Payments.create_single(attrs, :tenant_42)

:ok = BankingCircle.stop_client(:tenant_42)
```

## Usage

### Single payments

```elixir
{: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"
  })

{:ok, %{"status" => status}} = BankingCircle.Payments.get_status(payment["id"])
```

Invalid input is caught **before any network call**, via an
`Ecto.Changeset`:

```elixir
{:error, changeset} = BankingCircle.Payments.create_single(%{currency: "euros"})
Ecto.Changeset.traverse_errors(changeset, fn {msg, _} -> msg end)
#=> %{currency: ["must be a 3-letter ISO 4217 code"], ...}
```

### Bulk payments

```elixir
rows = [
  %{debtor_account_id: "acc_1", amount: Decimal.new("10.00"), currency: "EUR", ...},
  %{debtor_account_id: "acc_1", amount: Decimal.new("20.00"), currency: "EUR", ...}
]

{:ok, bulk} = BankingCircle.Payments.create_bulk(rows)
{:ok, stats} = BankingCircle.Payments.get_bulk(bulk["id"])
```

A row failing validation is reported with a 1-based index matching
Banking Circle's documented `elementIndex` semantics, so client-side and
server-side validation errors read the same way:

```elixir
{:error, [{2, changeset}]} = BankingCircle.Payments.create_bulk([good_row, bad_row])
```

### Webhooks

```elixir
{:ok, sub} =
  BankingCircle.Webhooks.create_subscription(%{
    url: "https://myapp.example.com/webhooks/banking_circle",
    encryption_key: my_32_char_key,
    event_types: ["OutgoingPaymentBooked", "IncomingPaymentProcessed"],
    active: false # verify your receiver before flipping this on
  })
```

Verifying an inbound payload (see `BankingCircle.Webhook.Verifier` for
the full Plug example and important caveats about the checksum field):

```elixir
{:ok, event} =
  BankingCircle.Webhook.Verifier.verify_and_decrypt(raw_body,
    checksum: checksum_header,
    tag: tag_header,
    nonce: nonce_header,
    key: my_32_char_key
  )
```

### FX

Market order (filled instantly at the prevailing rate):

```elixir
{:ok, trade} =
  BankingCircle.FX.trade(%{
    client_order_id: "YourUniqueReference",
    buy_currency: "EUR",
    sell_currency: "GBP",
    amount: 10_000,
    amount_currency: "EUR",
    tenor: :on
  })
```

RFQ (get a firm 30-second quote, then trade against it — no `tenor` when trading a quote):

```elixir
{:ok, [quote]} =
  BankingCircle.FX.request_quotes([
    %{
      quote_request_id: Ecto.UUID.generate(),
      customer_id: "000012356",
      currency_pair: "EURUSD",
      amount: 10_000,
      amount_currency: "EUR",
      tenor: :on,
      request_type: :rfq
    }
  ])

{:ok, trade} =
  BankingCircle.FX.trade(%{
    client_order_id: "YourUniqueReference",
    buy_currency: "EUR",
    sell_currency: "USD",
    amount: 10_000,
    amount_currency: "EUR",
    quote_id: quote["quoteId"]
  })
```

Held rate, locked for up to 24 hours and reusable within your daily limits:

```elixir
{:ok, held} = BankingCircle.FX.held_rate("EUR", "GBP", 1440)
```

### Reporting

```elixir
# Blocks until ready — fine for scripts/IEx/background workers.
{:ok, report} = BankingCircle.Reporting.fetch_report(:reconciliation, %{from: ~D[2026-07-01], to: ~D[2026-07-10]})

# Or drive it yourself for a web request handler / background job:
{:ok, request_id} = BankingCircle.Reporting.request_report(:account_activity, %{account_id: "acc_123"})
{:processing, retry_after_ms} = BankingCircle.Reporting.poll_status(request_id)
# ... schedule a follow-up poll after retry_after_ms ...
{:complete, report_id} = BankingCircle.Reporting.poll_status(request_id)
{:ok, report} = BankingCircle.Reporting.download(report_id)
```

### Case Management

```elixir
{:ok, %{"questions" => questions}} = BankingCircle.Cases.get_rfi_case(case_id)

{:ok, %{"attachmentId" => attachment_id}} =
  BankingCircle.Cases.upload_attachment(case_id, File.read!("passport.pdf"), "passport.pdf", "application/pdf")

answers = BankingCircle.Cases.RFI.build_answers(%{
  0 => "1994-06-01",
  1 => {:attachments, [attachment_id]}
})

{:ok, _} = BankingCircle.Cases.submit_rfi_answers(case_id, %{answers: answers})
```

### Direct Debit Collections

```elixir
{:ok, collection} =
  BankingCircle.DirectDebit.initiate(%{
    creditor_account_id: "acc_123",
    mandate_id: "your-stored-mandate-id",
    debtor_iban: "DE89370400440532013000",
    amount: Decimal.new("25.00"),
    currency: "EUR",
    end_to_end_id: "INV-2026-001"
  })
```

### Correspondent / Agency Banking

```elixir
{:ok, payment} =
  BankingCircle.Payments.create_fi_to_fi(%{
    debtor_account: %{account: "NL4089009999910133", financial_institution: "AAAANL2LXXX", country: "NL"},
    debtor_name: "Debtor Name",
    creditor_account: %{account: "CH2289000000021111123", country: "CH"},
    creditor_name: "Creditor Name",
    amount: %{currency: "EUR", amount: "1.00"},
    instr_id: "Agency banking payment 1"
  })
```

### Recalls and traces

```elixir
{:ok, recall} = BankingCircle.Payments.initiate_recall(payment_id, "AC03")
{:ok, trace} = BankingCircle.Payments.initiate_trace(payment_id)
```

## Architecture

```
BankingCircle              — client lifecycle (start_client/stop_client)
├── Config                 — validated per-client config (NimbleOptions)
├── Environment             — sandbox/production host resolution
├── Auth.Token              — JWT + expiry helpers
├── Auth.TokenServer        — cached, single-flight-refreshed token per client
├── HTTP.Client              — shared Req pipeline: auth injection, errors
├── HTTP.Middleware.Retry    — jittered backoff, Retry-After, safe-methods-only
├── HTTP.Middleware.Idempotency — UUIDv4 Idempotency-Key generation/attachment
├── Error                   — normalizes both documented error body shapes
├── Payments                 — single & bulk payment lifecycle, recalls, traces, fi-to-fi
├── Accounts                 — balances, bookings, AHV
├── VirtualAccounts             — VIBAN listing, ordering, UBO details, closure
├── FX                        — market order / RFQ / held rate trading, trade history
├── FX.Stream                  — WebSocket streaming quotes + Market Order execution
├── Reporting                  — async report request/poll/download flow
├── Cases / Cases.RFI          — RFI & Recall case management
├── DirectDebit                — mandate-based collection initiation (idempotency-keyed)
├── ISO20022                   — pain.001/pacs.008/camt.053 XML transport
├── Webhooks                  — subscription management
├── Webhook.Verifier          — AES-256-GCM payload decrypt/verify
├── Schemas.Payment            — Ecto-changeset request validation
└── Schemas.BulkPayment         — batch validation + CSV rendering
```

### Why these design choices

- **Req over Tesla/HTTPoison**: Req is the current Elixir ecosystem
  default for new HTTP clients (built on Finch/Mint, first-class
  streaming, sane defaults). We lean on its *built-in* retry mechanism
  rather than reimplementing request/response steps against internals.
- **Ecto embedded schemas without a database**: changesets are simply the
  best-in-class validation/casting primitive available in Elixir; using
  them here costs nothing (no Repo, no migrations) and gets you field-level
  error reporting for free.
- **One GenServer per client for token caching**: concurrent callers
  racing a near-simultaneous token expiry collapse into a single outbound
  auth request because the GenServer mailbox serializes it — no separate
  locking primitive needed.
- **Retry policy refuses to retry a bare POST**: Banking Circle's
  idempotency-key support is currently scoped to Direct Debit Collections
  endpoints. Blindly retrying an unacknowledged payment POST elsewhere
  risks a duplicate payment, so the retry middleware only retries
  GET/HEAD or requests explicitly carrying an `Idempotency-Key` header.

## Telemetry

```elixir
:telemetry.attach_many(
  "banking-circle-logger",
  [
    [:banking_circle, :request, :start],
    [:banking_circle, :request, :stop],
    [:banking_circle, :request, :exception]
  ],
  &MyApp.Telemetry.handle_event/4,
  nil
)
```

See `BankingCircle.Telemetry` for the full event/measurement/metadata table.

## Development

This package was authored without a local Elixir toolchain available in
its build environment, so while every module has been written and
reviewed carefully against the Elixir/OTP and Req/Ecto APIs it relies on,
**run the test suite yourself before depending on this in production**:

```sh
mix deps.get
mix test
mix credo --strict
mix dialyzer
```

## License

MIT. See `LICENSE`.