Secure Banking API Development, Part 1: Design the Controls Before Writing Code
Start the banking API lifecycle with a reviewable design: business authority, data boundaries, transaction outcomes, secure failure and evidence for delivery.
Perspectives · Secure Banking API Development · Part 1
A channel team asks for a payment API. Its first proposal has a request body, a gateway route and a success response. Three decisions are still open: who may debit the account, when a transfer can be called complete, and what happens if the response disappears after posting.
Those are design decisions. Agreeing them before development gives security, operations and testing teams something concrete to verify. This first article sets out that design baseline. Later parts will follow the API through implementation, testing, release, operation and retirement.
Start with the banking action
Write a one-sentence purpose: who requests what, against which record, and with what permitted effect? Separate enquiries, commands and events. Name the business owner, the system that applies the effect and the team that resolves an uncertain outcome. Record whether the consumer is a customer channel, internal workload or partner, since the trust and support arrangements differ.
For a transfer, the middleware can validate and route a request. The authorised banking service decides whether the debit can proceed and establishes the outcome. For a read, a replicated ODS can reduce load when its freshness is acceptable. It remains query-only; it does not post, reverse or repair a transaction.
Define authority at three levels
Authenticate the caller, then authorise the operation, the specific object and the fields involved. A token with a transfer scope does not grant access to every debit account. Check the customer’s entitlement to the account and the authority for this transaction, including any required limits or approvals. OWASP separates object, property and function-level authorisation risks for good reason. [1]
At design review, draw the path across channel, gateway, integration and source systems. Mark where TLS terminates, where identity is re-established and how delegated customer context is validated. For OAuth integrations, specify issuer, audience, scope and expiry validation, and choose an appropriate client authentication and token protection model. RFC 9700 explains audience restriction and sender constraint. [2]
Decide how credentials are issued, rotated and revoked before the first integration. A partner credential should have a defined scope and owner. A design that works only until certificate renewal or failover is incomplete.
Design the data and response contract
Use a versioned interface description such as OpenAPI for HTTP APIs, then add the business rules it cannot establish by schema alone. Define amount precision, currency, identifiers, field ownership, redaction and the meaning of each status. Validate request and response fields explicitly; avoid passing a core system record through simply because it is available. [5]
Decide what each consumer needs to see. Avoid exposing raw internal errors or sensitive customer data. RFC 9457 provides a common structure for HTTP error details; the bank still needs stable error types and safe messages. Document which conditions can be retried, which require a status check and which require a corrected request. [4]
Make a lost response part of the design
In a fictional transfer API, a request is durably accepted and given a reference. An HTTP 202 response can communicate acceptance while processing continues; it does not confirm that the transfer posted. Agree how the client checks status and which record supports the final outcome. [3]
A correlation ID helps trace a call. An idempotency key identifies a permitted repeat under a defined contract. A business reference follows the transfer through processing and reconciliation. The design may relate these identifiers, but each must have a clear scope. Enforce duplicate protection at the point controlling the financial effect, including concurrent retries and alternate routes. Define the retention window and reject incompatible reuse of a key.
If the response is lost after a debit may have posted, recover the original outcome through the authoritative lookup or reconciliation path. A late event or an absent replicated record cannot, on its own, establish failure. Avoid accepting a second financial instruction as an automatic response to uncertainty.
Set limits and decide how the API fails
Specify a journey deadline, dependency timeouts, payload and page limits, concurrency budgets and consumer quotas. Agree which layer owns retries so multiple layers do not amplify load. Define what must stop when a dependency cannot establish authorisation or a financial outcome, and which noncritical reads may degrade safely. Exercise these choices during peak, batch and failover testing.
Record what operations must be able to see: safe correlation, business outcomes, tail latency, queue age and repeated failures. Mask unnecessary personal data and secrets. Tie each alert to an owner and a response, and include certificate expiry and deprecated-route traffic in the operational design.
The design evidence to take into implementation
| Decision | Evidence to retain | First test to plan |
|---|---|---|
| Business authority | Action, source of truth, accountable owner | A caller with valid credentials requests an unauthorised account. |
| Contract and data | Versioned schema, field rules, status and error meanings | A payload is structurally valid but violates a business rule. |
| Repeat safety | Key scope, expiry and authoritative recovery path | The service posts the transfer but the response is lost. |
| Capacity and failure | Deadline, quota and dependency behaviour | A downstream service slows during peak demand. |
| Lifecycle | Named consumers, compatibility policy and retirement plan | An old client uses the prior version during recovery. |
The end-to-end series
| Part | Focus |
|---|---|
| 1 · This article | Design decisions, trust boundaries and review evidence |
| 2 · Planned | Secure implementation: identity, authorisation, validation and secrets |
| 3 · Planned | Transaction integrity: idempotency, asynchronous flows and reconciliation |
| 4 · Planned | Testing and release: abuse cases, contract checks, load and failover |
| 5 · Planned | Operations and retirement: monitoring, versioning, migration and closure |
For the lifecycle context, see When Old APIs Stay Live. Part 2 will take the design baseline into code and gateway policy.
Continue with Learning
The token is valid. Can this account be debited? Review a fictional transfer API before it enters development.
Sources & further reading
- OWASP API Security Top 10
- RFC 9700 — OAuth 2.0 Security BCP
- RFC 9110 — HTTP Semantics
- RFC 9457 — Problem Details for HTTP APIs
- OpenAPI Specification
Put this perspective into practice.
Explore the concepts, make a decision and test what changes when the situation changes.
Topics: API Architecture, Banking Architecture, Inside the Banking Backbone, Operational Resilience, Perspective