An Open Banking API Is a Contract

--

Strip away the acronyms and an open banking API is a small, boring promise.

A bank says to a third-party app: if you bring me a customer who has agreed to share their data, I will hand you that data in a predictable shape, through a predictable door, using a predictable key, and I will tell you in a predictable way when something goes wrong.

Four predictable things. That is the whole deal.

When all four hold, a personal-finance app can read your transactions and tell you that you spend too much on coffee. A small-business lending platform can read a business’s cash flow and approve a loan in a day. A new payments app can move your money without ever seeing your bank password.

When even one of those predictabilities slips, the deal still looks like it is working. Calls return 200. Dashboards stay green. But the data flowing through is wrong, or incomplete, or describes a customer who no longer exists. The contract has broken silently, and the only place anyone can see it break is in the documentation that was supposed to describe the contract.

The Contract, Stated Plainly

A useful way to think about an open banking API is as a four-part contract.

Part one: a predictable shape for the data. Every account balance, transaction, standing order, and account holder comes back in the same schema, every time.

Part two: a predictable way to ask for permission. The customer sees a consent screen, agrees to specific scopes, and can revoke at any time.

Part three: a predictable way to authorize. The third-party app proves who it is with a credential the bank issued, not with the customer’s password.

Part four: a predictable way to fail. A 401 means one specific thing. A 429 means one specific thing. A 403 means one specific thing.

The UK Open Banking Standard names these four predictabilities as the read-write requirements every UK bank serving more than a small customer base has to meet. The EU’s PSD2 regulatory technical standards say much the same in different words.

The docs published by each bank are how that bank explains, to the developers building on top of it, exactly what it has chosen inside the room the regulation gave it.

When the docs and the API agree, the contract holds.

Where the Contract Quietly Breaks

A contract breaks in a courtroom. A documentation contract breaks in a way nobody notices for weeks.

There are four places it tends to break, one for each part of the deal.

The shape drifts. Documented schema lists 12 fields. Production returns 14. The two new fields are a merchant category code and a payment scheme identifier. A budgeting app reading the response ignores the unknowns. It still works. But the spending categories the customer sees are derived from a stale heuristic when fresh logic is sitting unused in the response. The app cannot use what the docs do not say is there.

The permission drifts. Documented consent flow lists 5 scopes. Production added a 6th, required for standing-orders endpoints. The app requests the documented 5, gets a token, and the standing-orders endpoint returns a 200 with an empty array. The app interprets empty as “no standing orders.” The customer has six. They call support to ask why their rent payment is missing.

The credential drifts. Documented authorization is OAuth 2 bearer tokens. Production migrated higher-value endpoints to mutual TLS. The app, holding only a bearer, can read balances fine. The first payment attempt fails with a TLS handshake error. The on-call engineer spends two hours hunting a network problem that does not exist.

The errors drift. Documented meaning of 429 is “too many requests.” Production now returns 429 for a second case: “consent revoked in the last 60 seconds.” The app retries, hits the same 429, retries, and the actual rate limiter bans the app for an hour. One customer revoked consent. Now the app cannot serve any of its customers using that bank.

Every drift is a contract violation that does not look like one because the call returns successfully in some cases.

Why the Docs Are the Only Place This Gets Caught

A test environment catches a broken endpoint. Monitoring catches an outage. A regulator catches a serious incident, eventually.

None of them catch silent contract drift. Silent drift looks identical to a healthy system from every observation point except one: a developer reading the docs and finding they describe a different system than the one answering when called.

The Postman 2025 State of the API Report found that 55% of teams cite documentation gaps as their top collaboration challenge. In open banking, “collaboration” includes the regulator. A 2024 McKinsey analysis of open banking put the value at stake at hundreds of billions of dollars across mature markets. That value lives or dies on trust that the contract holds. The contract lives or dies in the docs.

Three Rules

If the docs are the contract surface, then changes to the API are changes to the contract, and the docs ship in the same release.

The schema in the docs is the schema in production. Every consent scope and error code is documented before it is enforced. Deprecations ship with a date and an alternative.

Not best-practice suggestions. The operational form of the regulatory promise that a documented API is a usable API.

The One-Sentence Version

An open banking API is a four-part contract, the docs are the contract, and when the two disagree the only people who notice are the customers calling support.

EkLine keeps fintech API documentation in lockstep with the running API.