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 customer's account information 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 entire 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 instead of a week. A new payments app can move money on your behalf without ever seeing your bank password.
When even one of those four 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.
This post is about the four predictabilities, where they leak, and why the docs are the only place to catch the leak before a regulator does.
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. A "transaction" has the same fields whether the customer banks with a 200-year-old institution or a digital-first challenger.
Part two: a predictable way to ask for permission. The customer sees a consent screen. The screen lists the specific things the app wants to do, like "read your last 90 days of transactions" or "initiate a payment of up to £500." The customer says yes or no. They can change their mind later.
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. The credential can be revoked. The credential cannot be reused by a different app.
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 app reading the response knows what to do next without guessing.
These four predictabilities are what regulators codified. The UK's Open Banking Standard names them as the read-write requirements that 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 shape, exactly what permission flow, exactly what credential, and exactly what error codes it has chosen inside the room the regulation gave it.
When the docs and the running API agree, the contract holds.
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 documented schema for a transaction lists twelve fields. Production has started returning fourteen. The two new fields are a merchant category code and a payment scheme identifier.
A budgeting app reading the response ignores the two unknown fields. It still works. Balances still tally. The customer still sees their spending broken down by what looks like category.
But the category breakdown is now derived from a heuristic the app built two years ago, not from the merchant category code the bank started returning four months ago. The app is making the customer's spending decisions on stale logic when fresh logic is sitting unused in the response payload.
This is the most common shape of drift, and the easiest to miss. The API got better. The docs did not catch up. The app cannot use what it does not know is there.
The documented consent flow lists five scopes a third-party app can request. Production has added a sixth scope, required for any endpoint that touches standing orders.
The app, built against the documented five scopes, requests the five it knows about. The bank's authorization server returns a token. The token works for four of the five endpoints the app uses. The fifth endpoint, the one that lists standing orders, returns a 200 with an empty array.
The app interprets "empty array" as "this customer has no standing orders." The customer, who has six standing orders, calls support to ask why their rent payment is missing from the app.
The drift here is silent because empty data and missing-permission data look identical to a client unless the docs say otherwise. The docs were the only place the new scope could have been announced.
The documented authorization is OAuth 2 with bearer tokens. Production has migrated higher-value endpoints to mutual TLS, where both the bank and the app present certificates.
The app, holding only a bearer token, can still call the lower-value endpoints. Read-only account information works fine. The first time the customer tries to initiate a payment through the app, the request fails with a TLS handshake error the app never expected.
The customer sees a generic "something went wrong" message. The app's error log fills with cipher mismatches. The on-call engineer spends two hours hunting a network problem that does not exist. The actual problem is that the docs described one credential and production now requires two.
The documented meaning of a 429 is "you are sending requests too fast." Production has started returning 429 for a second case: "the customer revoked consent in the last sixty seconds and our consent cache is still warm."
The app sees 429 and does what good clients do: it waits and retries. The retry hits the same 429. The retry-after header points to a future where the consent will still be revoked. The app retries again. After three retries the bank's actual rate limiter trips and bans the app's IP for an hour.
Now the app cannot serve any of its customers using that bank, because one customer revoked consent and the documented meaning of 429 did not warn the app that "revoked consent" was now a sub-case.
A test environment will catch a broken endpoint. Monitoring will catch an outage. A regulator will catch a serious incident, eventually.
None of those catch silent contract drift. Silent contract 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 that answers when called.
That is why the docs are not a deliverable. They are the contract surface. They are where a third-party app discovers the shape of the data, the consent flow, the credential, and the error semantics it has to honor. If the docs are wrong, every app trusting them is making decisions on bad terms, even when every individual call returns 200.
The Postman 2025 State of the API Report found that fifty-five percent of teams cite documentation gaps as their top collaboration challenge across organizations. In open banking, "collaboration" includes the regulator. The Financial Conduct Authority and the European Banking Authority both have explicit guidance that documented behavior must match production behavior, because a third-party app cannot be expected to comply with rules it cannot read.
A 2024 McKinsey analysis of open banking adoption put the value at stake at hundreds of billions of dollars across mature markets. That value lives or dies on the trust that the contract holds. The contract lives or dies in the docs.
If the docs are the contract surface, then changes to the API are changes to the contract, and the docs need to ship in the same release as the API change. Not the next sprint. Not after QA. The same release.
Three rules follow from that.
The schema in the docs is the schema in production. If the API adds a field, the docs add the field on the same merge. Generated reference docs help. Hand-edited reference docs, in an open banking context, are a contract risk.
Every consent scope and every error code is documented before it is enforced. If a new scope becomes required on Tuesday, the docs say so on Monday. Otherwise the apps building against the public documentation are operating in good faith on a contract they have not been told has changed.
Deprecations come with a date and an alternative. If bearer tokens will stop working on a high-value endpoint in ninety days, the docs say so, ninety days in advance, with a link to the mTLS migration guide. Silent deprecations are silent contract breaks.
These are not best-practice suggestions. In open banking they are the operational form of the regulatory promise that a documented API is a usable API.
An open banking API is a four-part contract. The docs are the contract. When the docs and the API disagree, the contract is broken, and the only people who notice are the customers calling support to ask why their money looks wrong.
That is why the docs matter more in this industry than in almost any other. Not because developer experience is nice. Because the contract is the product.
EkLine helps fintech teams keep their API documentation in lockstep with their running APIs by checking every doc change against the live spec, the consent model, and the published error catalog. If your team ships open banking endpoints, see how the checks work.
