API-first banking platform design patterns

API-first in banking means designing the API contract — endpoints, schemas, authentication, error formats — before writing any implementation code. Every banking capability (accounts, payments, lending, compliance) is modelled as an API-accessible resource from inception, rather than being added as an afterthought for partner integrations. This approach ensures that internal product teams and external fintech partners access the same well-designed interface, enables consistent SDK and documentation generation from the API spec, and makes the platform inherently composable for embedded finance use cases.

FAPI (Financial-grade API) is a security profile for OAuth 2.0 designed by the OpenID Foundation for banking and other high-security API contexts. It adds mandatory security measures beyond standard OAuth 2.0: PKCE (Proof Key for Code Exchange) to prevent authorisation code interception; PAR (Pushed Authorisation Requests) to secure the authorisation request; JARM (JWT Secured Authorisation Response Mode) to secure the authorisation response; mTLS (mutual TLS) for client authentication; and signed request objects. FAPI is required for Open Banking implementations in the UK (OBIE standards), EU (PSD2), Australia (CDR), and Brazil (Open Finance) because standard OAuth 2.0 does not provide sufficient protection for financial data and payment initiation.

Idempotency keys prevent duplicate financial operations when network failures cause clients to retry requests. Without idempotency, a client that sends a payment initiation request and receives a network timeout cannot safely retry — the original request may have succeeded, and retrying would create a duplicate payment. With idempotency keys, the client sends the same idempotency key with each retry, and the server guarantees that the operation is only executed once, returning the same response for any subsequent request with the same key. Idempotency keys are mandatory for any API endpoint that creates or modifies financial state.

The Backend-for-Frontend pattern creates a dedicated API gateway layer for each type of consumer — a mobile BFF, a web BFF, a partner integration BFF — that aggregates responses from core banking microservices into optimised payloads for that specific consumer. Instead of a generic API that returns all possible data (which the mobile app then filters), the mobile BFF returns exactly the fields needed for each screen. BFFs prevent over-fetching (returning more data than the consumer needs) and under-fetching (requiring multiple API calls to assemble a UI). In banking, BFFs also allow channel-specific security policies, rate limits, and response caching strategies.

Banking APIs should use URL path versioning (/v1/, /v2/) for major breaking changes, and only ship non-breaking additive changes (new optional fields, new endpoints) in minor releases. Breaking changes include: removing fields, changing field data types, changing enum values, and changing endpoint semantics. Non-breaking changes include: adding new optional response fields, adding optional request parameters, and adding new endpoints. Deprecated API versions should be maintained for a minimum of 12 months after announcing sunset, with 429 responses directing clients to migrate. Always publish detailed changelogs distinguishing breaking from non-breaking changes.

RFC 9457 (Problem Details for HTTP APIs) defines a standardised JSON response format for HTTP API errors. It specifies a structured object with fields: "type" (a URI identifying the error type, linking to documentation), "title" (human-readable summary), "status" (HTTP status code), "detail" (human-readable specific explanation of this instance), and "instance" (URI identifying the specific request/resource that caused the error). Banking APIs extend this with machine-readable error codes, trace IDs for debugging, and domain-specific fields (e.g., available balance on an insufficient funds error). Using Problem Details enables partner systems to handle errors programmatically without parsing free-text messages.

Banking APIs should implement tier-based rate limits by partner type (sandbox, standard, enterprise), using a sliding window algorithm (not fixed window) to prevent burst exploitation at window resets. Rate limits should vary by endpoint type — payment initiations get lower limits than balance reads, reflecting their higher processing cost and risk. All 429 responses must include Retry-After and rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Rate limits should be documented in the API developer portal and negotiable for enterprise partners with guaranteed SLAs.

Banking webhook design should follow these principles: use HTTPS endpoints with TLS 1.2+ only; sign all webhook payloads with HMAC-SHA256 using a partner-specific secret, included in an X-Webhook-Signature header for partner verification; include an idempotency key (event ID) in every payload so partners can deduplicate retried deliveries; use structured event type naming (payment.authorised, transaction.posted, kyc.approved); guarantee at-least-once delivery with automatic retry on non-2xx responses; provide a webhook delivery log in the partner portal for debugging; and support webhook endpoint validation (send a challenge on registration that the partner must return).