Banking Bridge

The Banking Bridge connector polls a Banking Bridge workspace and surfaces accounts, balances, and payments as read-only streams. It applies Connectivity's most extensive per-payment enrichment: end-to-end IDs, mandate IDs, clearing-system references, creditor info, and remittance fields all land under com.formance.connectors.bankingbridge.* on every payment.

Available from Payments 3.3.0. Source: ee/plugins/bankingbridge.

Prerequisites#

You need a Banking Bridge workspace and a clientID + clientSecret pair. Banking Bridge uses OAuth2 client-credentials against a separate authEndpoint; the connector exchanges the credentials for a short-lived bearer token and refreshes automatically.

Installation#

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

With config.json containing:

{
  "name": "string",
  "clientID": "string",
  "clientSecret": "string",
  "endpoint": "https://api.bankingbridge.example",
  "authEndpoint": "https://auth.bankingbridge.example"
}

Configuration fields#

Capabilities#

• FETCH_ACCOUNTS — internal accounts via GET /accounts, paginated by an opaque cursor + LastSeenImportedAt watermark.
• FETCH_BALANCES — per-account balance, independent periodic root.
• FETCH_PAYMENTS — GET /transactions, each row carrying the full enrichment set under com.formance.connectors.bankingbridge.*.

Payouts, transfers, bank-account creation, and webhooks are not implemented. Banking Bridge is a read-only observation surface.

Account model#

Every Connectivity internal account is one Banking Bridge /accounts row (a bank account observed via one of the aggregated providers). The reference is the Banking Bridge account reference; name is the upstream name; defaultAsset comes from Banking Bridge's defaultAsset field (already UMN-formatted); createdAt is the upstream ImportedAt. No EXTERNAL accounts are emitted. See Accounts for the cross-connector model.

Asset model#

Uppercase ISO 4217, formatted to UMN at standard precision. Amounts are already in minor units — no scaling.

Status mapping#

Scheme mapping#

Banking Bridge tags each transaction with an ISO 20022 triplet (Domain.Family.SubFamily). The connector collapses it into Connectivity's PaymentScheme + PaymentType via schemes.go:

• PMNT.ICRD / PMNT.MCRD (cards) → CARD_*, PAY-IN or PAYOUT per IssuedX vs ReceivedX.
• PMNT.ICDT / PMNT.RCDT (credit transfers) → SEPA / WIRE per sub-family.
• PMNT.IDDT / PMNT.RDDT (direct debits) → SEPA_DEBIT.
• PMNT.IRCT / PMNT.RRCT (real-time SCT) → SEPA_INSTANT.
• Unknown / MCOP / MDOP → UNKNOWN, classified OTHER.

Metadata keys#

Banking Bridge fields land under com.formance.connectors.bankingbridge.* (not com.bankingbridge.spec/) — Banking Bridge is the canonical example of the payment-reference enrichment pattern. Operationally useful keys:

• Account: iban, bic, currency_code, account_type, provider_name, provider_id, branch_code, imported_at.
• Payment (always emitted when populated by the provider):
  • End-to-end identifiers: end_to_end_id, instruction_id, transaction_id, mandate_id, clearing_system_reference.
  • Counterparty info: debtor_name, debtor_iban, debtor_bic, creditor_name, creditor_iban, creditor_bic.
  • Creditor reference: creditor_reference_type, creditor_reference_value, creditor_reference_issuer.
  • Remittance: remittance_information_unstructured, remittance_information_structured.
  • Bank-side fields: bank_transaction_code (the raw Domain.Family.SubFamily triplet), value_date, booking_date, provider_name, provider_id.

Workflow tree#

FetchAccounts (periodic root)
FetchPayments  (periodic root)
FetchBalances  (periodic root)

Each root holds its own cursor + LastSeenImportedAt watermark and advances independently — Banking Bridge's /transactions endpoint is workspace-global, not per-account.

Pagination and recovery#

Each capability persists (cursor, lastSeenImportedAt) in platform-managed State. The cursor is opaque; lastSeenImportedAt re-seeds the next cycle's lower bound after the current page set is exhausted. Restarts resume from the last committed State; the engine dedupes by PSPPayment.Reference.

Known gaps#

• Outbound initiation (transfers, payouts, bank-account creation) is not implemented.
• Webhooks are not wired.
• Reversals are not modelled as reversal events — reversed transactions appear as new rows with the RRTN / XRTN sub-family code.
• Multi-workspace tenants: one connector install covers one Banking Bridge workspace.