bankingcircle

README

bankingcircle-go

A complete, production-grade, dependency-free Go client for the Banking Circle Connect API: cross-border payments, accounts, virtual accounts (VIBANs), FX (trading, RFQ, held rates, and live WebSocket streaming), reporting, case management (RFI/recall), direct debit collections, ISO20022 message transport, and webhooks.

This is a Go port of the banking_circle Elixir hex package, restructured as an idiomatic Go SDK.

import "github.com/iamkanishka/bankingcircle-go"

Design goals

• Zero third-party runtime dependencies. Standard library only — including a from-scratch RFC 6455 WebSocket client for FX streaming and a UUIDv4 generator for idempotency keys.
• Domain-driven package layout. Each bounded context (payments, accounts, fx, ...) owns its entities, validation, and service in one package, built on a shared kernel in internal/.
• Client-side validation before any network call. Invalid payment fields, malformed IBANs, etc. fail fast as a *bankingcircle.Error without hitting the network.
• Safe retries. Full-jitter exponential backoff, but only for GET/HEAD or requests carrying an Idempotency-Key — a bare POST is never auto-retried, so a flaky network can't duplicate a payment.
• Structured, classifiable errors. *bankingcircle.Error normalizes every documented Banking Circle error body shape, with an ErrorKind you can branch on.
• context.Context everywhere a network call happens, for cancellation, deadlines, and tracing propagation.

Install

go get github.com/iamkanishka/bankingcircle-go

Requires Go 1.25+.

Quick start

package main

import (
	"context"
	"log"
	"time"

	"github.com/iamkanishka/bankingcircle-go"
	"github.com/iamkanishka/bankingcircle-go/payments"
)

func main() {
	client, err := bankingcircle.New(
		bankingcircle.WithEnvironment(bankingcircle.Sandbox),
		bankingcircle.WithCredentials(username, password, certThumbprint),
		bankingcircle.WithRequestTimeout(20*time.Second),
	)
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	payment, err := client.Payments.CreateSingle(ctx, payments.CreateSingleInput{
		DebtorAccountID:      "acc_123",
		Amount:               "100.50",
		Currency:             "EUR",
		CreditorName:         "Jane Doe",
		CreditorIBAN:         "DE89370400440532013000",
		TransactionReference: "INV-2026-001",
	})
	if err != nil {
		if bcErr, ok := bankingcircle.AsError(err); ok {
			log.Fatalf("payment failed [%s]: %s", bcErr.Kind, bcErr.Message)
		}
		log.Fatal(err)
	}
	log.Printf("payment created: %v", payment)
}

See examples/basic for a fuller runnable walkthrough (accounts, a payment, and an FX rate lookup) and examples/webhookreceiver for a webhook HTTP handler.

Configuration

client, err := bankingcircle.New(
	bankingcircle.WithEnvironment(bankingcircle.Sandbox), // or bankingcircle.Production
	bankingcircle.WithCredentials(username, password, certThumbprint),
	bankingcircle.WithClientCertificate(certPath, keyPath), // mTLS, required by Banking Circle
	bankingcircle.WithRequestTimeout(20*time.Second),        // default 15s
	bankingcircle.WithMaxRetries(3),                          // default 3
	bankingcircle.WithRetryBaseDelay(250*time.Millisecond),   // default 250ms, capped at 8s
	bankingcircle.WithTelemetry(myTelemetry),                 // see Telemetry below
	bankingcircle.WithName("my-service"),                     // telemetry label only
)

WithEnvironment and WithCredentials are effectively required (the default environment is Sandbox, but you'll want to set it explicitly); everything else has a sensible default. New validates configuration and returns an error immediately — no network call is made during construction, since tokens are fetched lazily and cached.

A *Client is safe for concurrent use; build one per Banking Circle account/legal-entity credential pair and share it.

Services

Every bounded context is exposed as a field on *bankingcircle.Client, and documented in its own package:

Field	Package	Covers
client.Payments	payments	Single & bulk payments, status, cancellation, MT103, recalls, traces, Correspondent/Agency Banking (FI-to-FI)
client.Accounts	accounts	Listing, balances, bookings, Account Holder Verification
client.VirtualAccounts	virtualaccounts	VIBAN listing, ordering, customer/UBO details, closure
client.FX	fx	Market order / RFQ / held-rate trading, indicative rates, trade history, WebSocket streaming (client.StreamFX)
client.Reporting	reporting	Async report request/poll/download, sync reconciliation report
client.Cases	cases	RFI/Recall case listing, detail, attachments, answers
client.DirectDebit	directdebit	Mandate-referenced collection initiation (idempotency-key supported)
client.ISO20022	iso20022	pain.001/pacs.008 XML transport, camt.053 statements
client.Webhooks	webhooks	Subscription CRUD, sandbox simulation
—	webhook	Network-free AES-256-GCM payload verification/decryption

Payments

// Single payment
payment, err := client.Payments.CreateSingle(ctx, payments.CreateSingleInput{
	DebtorAccountID:       "acc_123",
	Amount:                "100.50",
	Currency:              "EUR",
	CreditorName:          "Jane Doe",
	CreditorIBAN:          "DE89370400440532013000",
	TransactionReference:  "INV-2026-001",
	Urgency:               payments.UrgencyInstant, // optional, defaults to standard
})

// Bulk payment — every row validated client-side; a single invalid row
// rejects the whole batch before any network call, with 1-based
// row indices matching Banking Circle's elementIndex error semantics.
result, err := client.Payments.CreateBulk(ctx, []payments.CreateSingleInput{
	{DebtorAccountID: "acc_123", Amount: "10.00", Currency: "EUR", /* ... */},
	{DebtorAccountID: "acc_123", Amount: "20.00", Currency: "EUR", /* ... */},
})
var bulkErr *payments.BulkValidationError
if errors.As(err, &bulkErr) {
	for _, row := range bulkErr.Rows {
		log.Printf("row %d: %v", row.Index, row.Err)
	}
}

// Recall / trace a payment
client.Payments.InitiateRecall(ctx, paymentID, payments.RecallReasonWrongAmount)
client.Payments.InitiateTrace(ctx, paymentID)

Only directdebit.Initiate currently carries documented idempotency-key support — CreateSingle/CreateBulk are never auto-retried by the shared HTTP pipeline for exactly that reason. If a payment request times out, check GetByTransactionReference before resubmitting.

FX — REST and streaming

// Market order
trade, err := client.FX.Trade(ctx, fx.TradeInput{
	ClientOrderID:  "order-1",
	BuyCurrency:    "USD",
	SellCurrency:   "EUR",
	Amount:         "10000",
	AmountCurrency: "EUR",
	Tenor:          fx.TenorSpot,
})

// RFQ -> trade
quotes, _ := client.FX.RequestQuotes(ctx, []fx.QuoteRequest{
	{CurrencyOne: "EUR", CurrencyTwo: "USD", Amount: "10000", AmountCurrency: "EUR",
		Tenor: fx.TenorSpot, RequestType: fx.RequestTypeRFQ},
})
trade, err := client.FX.Trade(ctx, fx.TradeInput{
	ClientOrderID: "order-2", BuyCurrency: "USD", SellCurrency: "EUR",
	Amount: "10000", AmountCurrency: "EUR", QuoteID: quotes[0]["id"].(string),
})

// Live streaming quotes + Market Order execution
stream, err := client.StreamFX(ctx, fx.StreamParams{
	CustomerID: "000012345",
	Handler: func(msg fx.StreamMessage) {
		log.Printf("[%s] %v", msg.Type(), msg)
	},
})
defer stream.Close()
stream.Subscribe("EUR/USD", fx.TenorSpot, 0)
stream.MarketOrder(fx.StreamOrderInput{
	ClientOrderID: "stream-order-1", BuyCurrency: "EUR", SellCurrency: "USD",
	AmountCurrency: "EUR", Amount: "3000000", Tenor: fx.TenorSpot,
})

Reporting

// Blocking convenience wrapper around request -> poll -> download
body, err := client.Reporting.FetchReport(ctx, reporting.ReportReconciliation,
	map[string]interface{}{"fromDate": "2026-07-01", "toDate": "2026-07-27"},
	reporting.FetchReportOptions{Timeout: 3 * time.Minute},
)

// Or drive the flow yourself (e.g. from a background job)
requestID, _ := client.Reporting.RequestReport(ctx, reporting.ReportAccountActivity, attrs)
outcome, _ := client.Reporting.PollStatus(ctx, requestID)
if outcome.Complete {
	body, _ := client.Reporting.Download(ctx, outcome.ReportID)
}

Webhooks

// Subscribe (see the webhooks package)
sub, err := client.Webhooks.CreateSubscription(ctx, webhooks.CreateSubscriptionInput{
	URL:           "https://example.com/webhooks/banking-circle",
	EncryptionKey: myThirtyTwoCharacterKey,
	EventTypes:    []string{"PaymentProcessed", "CaseOpened"},
})

// Verify + decrypt an inbound payload (network-free — call this from
// your own HTTP handler; see examples/webhookreceiver)
event, err := webhook.VerifyAndDecrypt(body, webhook.Options{
	Checksum: r.Header.Get("X-Bc-Checksum"),
	Tag:      r.Header.Get("X-Bc-Auth-Tag"),
	Nonce:    r.Header.Get("X-Bc-Nonce"),
	Key:      myThirtyTwoCharacterKey,
})

Error handling

Every failure mode — transport errors, HTTP 4xx/5xx, auth failures, and client-side validation — surfaces as a *bankingcircle.Error:

_, err := client.Payments.CreateSingle(ctx, input)
if bcErr, ok := bankingcircle.AsError(err); ok {
	switch bcErr.Kind {
	case bankingcircle.KindValidation:
		// client-side or 422 validation problem; see bcErr.Details
	case bankingcircle.KindRateLimited:
		// 429; bcErr.RetryAfterMs is populated if the server sent one
	case bankingcircle.KindAuth:
		// 401/403
	}
	if bcErr.Retryable() {
		// KindRateLimited, KindServerError, KindTimeout, KindTransport
	}
}

bcErr.Details normalizes both of Banking Circle's documented error body shapes (the single-object propertyName/errorCode/errorDescription shape, and the bulk-operation fieldIndex/elementIndex list shape) into one []ErrorDetail.

Telemetry

Implement bankingcircle.Telemetry to receive lifecycle events for every outgoing request (across every service):

type Telemetry interface {
	OnRequestStart(ctx context.Context, method, path string)
	OnRequestStop(ctx context.Context, method, path string, duration time.Duration, status int, err error)
}

Wire it up with bankingcircle.WithTelemetry(myImpl). Use it to feed Prometheus, OpenTelemetry, or structured logging.

Project structure

bankingcircle-go/
├── bankingcircle.go        # Client facade: wires config, auth, transport, and every service
├── config.go, options.go   # Config + functional options
├── environment.go          # Sandbox/Production host resolution
├── errors.go, telemetry.go # Public error & telemetry types
├── internal/
│   ├── apierrors/          # Canonical Error type + parsing (both documented error shapes)
│   ├── auth/                # Cached, single-flight-refreshed OAuth2 token manager
│   ├── httpclient/          # Shared request pipeline: retries, idempotency, telemetry
│   └── wsclient/            # From-scratch RFC 6455 WebSocket client (stdlib only)
├── payments/                # Entities + validation + service, one bounded context per package
├── accounts/
├── virtualaccounts/
├── fx/                      # + stream.go for WebSocket quote streaming / Market Orders
├── reporting/
├── cases/
├── directdebit/
├── iso20022/
├── webhooks/                # Subscription management (network)
├── webhook/                 # Payload verification/decryption (network-free)
└── examples/
    ├── basic/
    └── webhookreceiver/

Each bounded-context package is self-contained: its entities, client-side validation, and service methods live together, on top of the shared kernel in internal/. internal/ packages never import the root bankingcircle package (avoiding import cycles) — public types like bankingcircle.Error are type aliases onto their internal/apierrors counterparts, so every service package can construct and return them directly.

Confidence notes / scope

This SDK implements the full documented Banking Circle Connect API surface, with two exceptions, both explained in the bankingcircle package doc:

• Correspondent/Agency Banking over raw SWIFT FIN (MT101/MT103 message exchange) is not an HTTP endpoint and is out of scope.
• Aliases (PayID, etc.) are described in Banking Circle's docs but no REST endpoint paths/payload shapes are published anywhere we could find — inventing plausible-looking ones for a payment-routing feature would be actively dangerous, not just inconvenient.

Additionally, virtualaccounts.Service.Order's exact endpoint path/payload shape is inferred from documentation terminology rather than confirmed directly against the API reference — see that package's doc comment, and verify against your sandbox before relying on it in production. Everything else has been checked against the reference Elixir client's documented behavior.

Development

make build        # go build ./...
make test-race     # go test ./... -race -count=1
make vet           # go vet ./...
make fmt-check      # gofmt -l .
make lint           # golangci-lint run ./... (see .golangci.yml)
make ci             # fmt-check + vet + test-race + examples build

License

MIT — see LICENSE.

Documentation

Overview

Package bankingcircle is a production-grade Go client for the Banking Circle Connect API (https://docs.bankingcircleconnect.com): cross-border payments (single & bulk), accounts, virtual accounts (VIBANs), FX (market order / RFQ / held-rate trading, plus WebSocket quote streaming), reporting, case management (RFI / recall), direct debit collections, ISO20022 message transport, and webhooks (subscription management + AES-256-GCM payload verification).

Design goals

• Zero third-party runtime dependencies (standard library only).
• Domain-driven package layout: each bounded context (payments, accounts, fx, ...) owns its entities, validation, and service in a single package, built on top of the shared kernel in internal/.
• OAuth2/JWT auth with cached, single-flight-refreshed tokens.
• Client-side request validation before any network call.
• Safe retries with full-jitter exponential backoff, restricted to idempotent/idempotency-keyed requests to avoid duplicate payment submission.
• Structured, classifiable errors (*bankingcircle.Error) normalizing both of Banking Circle's documented error body shapes.
• context.Context on every network-calling method for cancellation, deadlines, and tracing propagation.

Quick start

client, err := bankingcircle.New(
	bankingcircle.WithEnvironment(bankingcircle.Sandbox),
	bankingcircle.WithCredentials(username, password, certThumbprint),
)
if err != nil {
	log.Fatal(err)
}

payment, err := client.Payments.CreateSingle(ctx, payments.CreateSingleInput{
	DebtorAccountID:       "acc_123",
	Amount:                "100.50",
	Currency:              "EUR",
	CreditorName:          "Jane Doe",
	CreditorIBAN:          "DE89370400440532013000",
	TransactionReference:  "INV-2026-001",
})

Scope

This package implements the full documented Banking Circle Connect API surface: Authentication, Payments (single & bulk, recalls, traces, Correspondent/Agency Banking), Accounts (balances, bookings, AHV), Virtual Accounts, Webhooks (subscriptions + verification), FX (trading, RFQ, held rates, streaming), Reporting (async + synchronous reconciliation), Case Management (RFI/Recall), Direct Debit Collections, and ISO20022 message transport.

Deliberately out of scope: Correspondent/Agency Banking over the raw SWIFT FIN network (MT101/MT103 message exchange is not an HTTP endpoint), and Aliases (PayID, etc.) — Banking Circle's docs describe this feature but do not publish REST endpoint paths/payload shapes for it anywhere we could find; inventing plausible-looking endpoints for a payment-routing feature is actively dangerous, not just inconvenient.

See the README for full usage examples and the package-level docs of each bounded-context package (payments, accounts, virtualaccounts, fx, reporting, cases, directdebit, iso20022, webhooks, webhook) for details.

Index

• Constants
• type Client
  • func New(opts ...Option) (*Client, error)
  • func (c *Client) InvalidateToken()
  • func (c *Client) StreamFX(ctx context.Context, params fx.StreamParams) (*fx.Stream, error)
• type Config
• type Environment
  • func (e Environment) APIBaseURL() string
  • func (e Environment) AuthBaseURL() string
  • func (e Environment) Validate() error
  • func (e Environment) WebSocketURL() string
• type Error
  • func AsError(err error) (*Error, bool)
• type ErrorDetail
• type ErrorKind
• type MissingFieldError
• type NoopTelemetry
  • func (NoopTelemetry) OnRequestStart(context.Context, string, string)
  • func (NoopTelemetry) OnRequestStop(context.Context, string, string, time.Duration, int, error)
• type Option
  • func WithBaseURLOverrides(apiBaseURL, authBaseURL string) Option
  • func WithClientCertificate(certPath, keyPath string) Option
  • func WithCredentials(username, password, certificateThumbprint string) Option
  • func WithEnvironment(env Environment) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithMaxRetries(n int) Option
  • func WithName(name string) Option
  • func WithRequestTimeout(d time.Duration) Option
  • func WithRetryBaseDelay(d time.Duration) Option
  • func WithTelemetry(t Telemetry) Option
  • func WithWebhookEncryptionKey(key string) Option
• type Telemetry
• type ValidationError

Constants

const (
	KindTransport           = apierrors.KindTransport
	KindTimeout             = apierrors.KindTimeout
	KindAuth                = apierrors.KindAuth
	KindValidation          = apierrors.KindValidation
	KindRateLimited         = apierrors.KindRateLimited
	KindConcurrencyConflict = apierrors.KindConcurrencyConflict
	KindNotFound            = apierrors.KindNotFound
	KindClientError         = apierrors.KindClientError
	KindServerError         = apierrors.KindServerError
	KindUnexpectedResponse  = apierrors.KindUnexpectedResponse
)

Error kind constants — see ErrorKind.

Types

type Client

type Client struct {
	Payments        *payments.Service
	Accounts        *accounts.Service
	VirtualAccounts *virtualaccounts.Service
	FX              *fx.Service
	Reporting       *reporting.Service
	Cases           *cases.Service
	DirectDebit     *directdebit.Service
	ISO20022        *iso20022.Service
	Webhooks        *webhooks.Service
	// contains filtered or unexported fields
}

Client is a fully-configured Banking Circle Connect client. Build one with New. Every bounded-context service is exposed as a field — Payments, Accounts, VirtualAccounts, FX, Reporting, Cases, DirectDebit, ISO20022, Webhooks — each independently documented in its own package.

A Client is safe for concurrent use by multiple goroutines; create one Client per Banking Circle account/legal-entity credential pair and share it, rather than constructing one per request.

func New

func New(opts ...Option) (*Client, error)

New builds a Client from the given Options. WithEnvironment and WithCredentials are required; every other option has a sensible default. Returns an error if the resolved configuration is invalid (e.g. missing credentials, mismatched mTLS cert/key) — no network call is made during construction, since Banking Circle tokens are fetched lazily on first use and cached thereafter.

func (*Client) InvalidateToken

func (c *Client) InvalidateToken()

InvalidateToken discards the cached bearer token, forcing a fresh authorization request on the next API call. Rarely needed — the client refreshes proactively before expiry — but useful if you suspect a token was revoked out-of-band.

func (*Client) StreamFX

func (c *Client) StreamFX(ctx context.Context, params fx.StreamParams) (*fx.Stream, error)

StreamFX opens a new FX WebSocket streaming session (live quote subscriptions and Market Order execution) — see the fx package's Stream type for full documentation. The environment's FX WebSocket URL is resolved from this Client's configuration automatically.

type Config

type Config struct {
	Name        string
	Environment Environment

	Username              string
	Password              string
	CertificateThumbprint string

	// ClientCertPath / ClientKeyPath configure mTLS, which Banking Circle
	// requires at the transport layer in addition to Basic-auth
	// credentials at the token endpoint. Both must be set together, or
	// both left empty.
	ClientCertPath string
	ClientKeyPath  string

	// WebhookEncryptionKey is the 32-character pre-shared AES-256-GCM key
	// used by the webhook package to decrypt inbound payloads. Optional
	// here — it can also be passed per-call to webhook.VerifyAndDecrypt.
	WebhookEncryptionKey string

	RequestTimeout time.Duration
	MaxRetries     int
	RetryBaseDelay time.Duration

	// HTTPClient, if set, is used as the base HTTP client (its Transport
	// is reused for the no-redirect variant used by Reporting). Leave nil
	// to have one built automatically, applying mTLS if ClientCertPath /
	// ClientKeyPath are set.
	HTTPClient *http.Client

	Telemetry Telemetry

	// APIBaseURLOverride / AuthBaseURLOverride are test/proxy escape
	// hatches — not part of normal usage.
	APIBaseURLOverride  string
	AuthBaseURLOverride string
}

Config is the fully-resolved, validated configuration for one Client instance. Build it via New with functional Options rather than constructing it directly.

type Environment

type Environment string

Environment identifies which Banking Circle Connect environment a Client talks to. Sandbox and production use entirely separate hosts, credentials, and client certificates — mixing them up is the most common integration mistake, so Environment is the single source of truth for host resolution.

const (
	// Sandbox is Banking Circle's testing environment.
	Sandbox Environment = "sandbox"
	// Production is Banking Circle's live environment.
	Production Environment = "production"
)

func (Environment) APIBaseURL

func (e Environment) APIBaseURL() string

APIBaseURL returns the REST API base URL for e.

func (Environment) AuthBaseURL

func (e Environment) AuthBaseURL() string

AuthBaseURL returns the OAuth2 token endpoint base URL for e.

func (Environment) Validate

func (e Environment) Validate() error

Validate reports whether e is a recognized environment.

func (Environment) WebSocketURL

func (e Environment) WebSocketURL() string

WebSocketURL returns the FX streaming WebSocket URL for e.

type Error

type Error = apierrors.Error

Error is the 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.

func AsError

func AsError(err error) (*Error, bool)

AsError is a convenience for errors.As(err, &bcErr); it unwraps err to find a *bankingcircle.Error, if any is present in its chain.

type ErrorDetail

type ErrorDetail = apierrors.ErrorDetail

ErrorDetail is one normalized entry from either of Banking Circle's two documented error body shapes.

type ErrorKind

type ErrorKind = apierrors.ErrorKind

ErrorKind classifies the failure mode of an *Error.

type MissingFieldError

type MissingFieldError = apierrors.MissingFieldError

MissingFieldError is returned when a dynamically-required field (e.g. either Tenor or QuoteID on FX.Trade) is absent.

type NoopTelemetry

type NoopTelemetry struct{}

NoopTelemetry implements Telemetry with no-op methods; it is the default when WithTelemetry is not supplied.

func (NoopTelemetry) OnRequestStart

func (NoopTelemetry) OnRequestStart(context.Context, string, string)

OnRequestStart implements Telemetry.

func (NoopTelemetry) OnRequestStop

func (NoopTelemetry) OnRequestStop(context.Context, string, string, time.Duration, int, error)

OnRequestStop implements Telemetry.

type Option

type Option func(*Config)

Option configures a Client at construction time. See New.

func WithBaseURLOverrides

func WithBaseURLOverrides(apiBaseURL, authBaseURL string) Option

WithBaseURLOverrides overrides the API and/or auth base URLs — a test/proxy escape hatch, not for normal usage. Pass "" to leave either at its environment default.

func WithClientCertificate

func WithClientCertificate(certPath, keyPath string) Option

WithClientCertificate configures mTLS using a PEM certificate/key pair on disk. Banking Circle requires client-certificate authentication at the transport layer in addition to the Basic-auth credentials from WithCredentials.

func WithCredentials

func WithCredentials(username, password, certificateThumbprint string) Option

WithCredentials sets the OAuth2 Basic-auth username/password and the X-Certificate-Thumbprint header value Banking Circle requires at the token endpoint. Required.

func WithEnvironment

func WithEnvironment(env Environment) Option

WithEnvironment selects Sandbox or Production. Required.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient supplies a pre-configured *http.Client (e.g. with a custom Transport for proxying/mocking in tests). When set, mTLS configured via WithClientCertificate is ignored — configure it on the supplied client's Transport instead.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets how many additional attempts are made after the first, for eligible requests (GET/HEAD, or any method carrying an Idempotency-Key). Defaults to 3.

func WithName

func WithName(name string) Option

WithName sets a label for this client instance, used only in telemetry metadata — useful when a process holds multiple Clients (e.g. one per legal entity) and needs to tell their metrics apart.

func WithRequestTimeout

func WithRequestTimeout(d time.Duration) Option

WithRequestTimeout sets the per-request timeout (applied per attempt, not across retries). Defaults to 15s.

func WithRetryBaseDelay

func WithRetryBaseDelay(d time.Duration) Option

WithRetryBaseDelay sets the base delay for full-jitter exponential backoff between retries (capped at 8s). Defaults to 250ms.

func WithTelemetry

func WithTelemetry(t Telemetry) Option

WithTelemetry attaches a Telemetry implementation to receive per-request lifecycle events.

func WithWebhookEncryptionKey

func WithWebhookEncryptionKey(key string) Option

WithWebhookEncryptionKey sets the default 32-character pre-shared AES-256-GCM key used to decrypt inbound webhook payloads. Optional — it can also be passed per-call.

type Telemetry

type Telemetry interface {
	// OnRequestStart is called immediately before a request is sent.
	OnRequestStart(ctx context.Context, method, path string)
	// OnRequestStop is called after a request completes (successfully or
	// not), including retries — duration covers the full retry sequence.
	// err is non-nil only for transport-level failures (a non-2xx HTTP
	// response is not, itself, an error at this layer).
	OnRequestStop(ctx context.Context, method, path string, duration time.Duration, status int, err error)
}

Telemetry receives lifecycle notifications for every outgoing request, mirroring the :telemetry events emitted by the reference Elixir client ([:banking_circle, :request, :start|:stop|:exception]). Implement this interface and pass it via WithTelemetry to feed metrics/tracing systems (Prometheus, OpenTelemetry, structured logging, ...).

Implementations must be safe for concurrent use, since requests from every service (Payments, Accounts, FX, ...) share one Client.

type ValidationError

type ValidationError = apierrors.ValidationError

ValidationError represents a client-side validation failure raised before any network call is made.