Banking Circle

The Banking Circle connector polls a Banking Circle tenant and surfaces settlement accounts, balances, and transactions. It also initiates transfers and payouts, and registers new beneficiaries on Banking Circle's side.

Prerequisites#

You need a Banking Circle tenant and a mutual-TLS-capable API user. Authentication combines a username/password pair (for OAuth2) with a client certificate (userCertificate + userCertificateKey) on every call. The cert is PEM-encoded; supply certificate and key as multi-line strings in the config.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/bankingcircle \
  -H "Content-Type: application/json" \
  -d @config.json

Configuration fields#

Capabilities#

• FETCH_ACCOUNTS — settlement and customer accounts via GET /api/v1/accounts.
• FETCH_BALANCES — available + intraday balance per account.
• FETCH_PAYMENTS — transactions, classified PAY-IN / PAYOUT / TRANSFER by direction.
• CREATE_BANK_ACCOUNT — registers a beneficiary from a v3CreateBankAccount call.
• CREATE_TRANSFER — POST /api/v1/payments/singles between two Banking Circle accounts.
• CREATE_PAYOUT — POST /api/v1/payments/singles to a registered beneficiary.

Webhooks are not exposed on the API surface this connector reaches; refresh runs on the polling cycle.

Account model#

Every Connectivity internal account is one Banking Circle account from /api/v1/accounts — typically a settlement or customer ledger. The reference is the Banking Circle accountId; name is the description; defaultAsset is the account's currency. EXTERNAL accounts aren't pulled, but v3CreateBankAccount (via CREATE_BANK_ACCOUNT) registers a beneficiary on Banking Circle and links the result back. See Accounts for the cross-connector model.

Asset model#

Uppercase ISO 4217 (EUR, GBP, USD, …), formatted to UMN at standard precision. Amounts arrive as decimal strings; the connector applies major-to-minor scaling.

Status mapping#

Create* initiations schedule PollTransferStatus / PollPayoutStatus against the singles-payment endpoint until terminal.

Metadata keys#

Under com.bankingcircle.spec/:

• Account: account_id, iban, bic, currency_code, account_type.
• Payment: transaction_id, transaction_reference, end_to_end_id, payment_method, clearing_system.
• External account: beneficiary_id, country, iban, bic, routing_number.

Workflow tree#

FetchAccounts (periodic)
  ├── FetchBalances (periodic) — per account
  └── FetchPayments (periodic) — per account
CreateBankAccount / CreateTransfer / CreatePayout (event-driven)
  └── PollTransferStatus / PollPayoutStatus until terminal

Pagination and recovery#

Banking Circle transactions are pageNumber + pageSize. The connector persists the latest watermark per account in platform-managed State and re-fetches one cycle back on restart, deduping by PSPPayment.Reference.

Known gaps#

• Webhooks are not wired.
• Reversals (ReverseTransfer / ReversePayout) are not implemented; corrections live in Banking Circle's UI.
• External accounts via FETCH are not pulled — beneficiaries are managed via CreateBankAccount and persisted Connectivity-side.